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EDITOR'S NOTE 



One thing about magazine publishing: the wheel keeps turning no matter what* 
There can be no shps because of problems that crop np or any extra work that needs 
to be done; the “to press” date is set way in advance* So for this issue, having to deal 
with redesigning our layciut and having our technical editor out on jury duty for 
months, IVe been going crazy. The smiling face you see in this photo is not what Fve 
looked like for most of the last three months! 

But enough about me. Let's talk abcjut the redesign. As you’ve no doubt already 
noticed, we Ve changed deoelop\ cover to make it look more like those you’ll find on 
newsstands. WeVe added an eye-catching strip across the top and moved the article 
titles from the right side of the cover to the left, where tliey would peek out if the 
issues were stacked from left to right (imagine offset overlapping windows). 


CAROLINE ROSE 


WeVe changed the layout in the inside to fit a bit more on each page. Issues of develop 
will be slimmer than before, but you’ll still be getting the same amount of concent. 
We couldn’t resist tweaking a few other things while we w^ere at it. Specifically, 
“listing boxes” now help keep code together in one tidy place. But we still put code 
close to where it’s discussed, and we still place code in the body of the article if that 
makes more sense. 


Another change in this issue is a direct result of the aforementioned jury duty: Dave 
Johnson’s popular Veteran Neophyte column is missing. But don’t worry; it will 
return once justice has been served. xMeanwhile we do have two new columns: 
Balance of Power, widi PowerPC^'^-related tidbits from Dave Evans, and Newton 
Q & A, which lets you interrogate a llama and receive a T-shirt if he uses your ^ 
question. 


xAs always, we’d like your feedback. There will be more changes to come, and we 
really w^ant to know what W'orks for you and what doesn’t. So please, don’t just gripe 
(or sing our praises) among yourselves; drop us a line and give us yoirr $J}2! All 
information about w^ho to contact for what is now located in one handy place, on the 
inside front cover (along with other irresistible tweaks). 


By letting us know how w^e can improve, you help us win awards like the one that we 
learned of W'hile working on this issue: an Award of Distinction, and Best of Category 
(xMonthlyor Quarterly Magazines), in the Society for Technical Communication’s 
1993 Northern California technical Publications Competition. So thanks, and please 
keep it conung! 



Caroline Rose 
Editor 


CAROLINE ROSE (AppleLink CROSE] was port 
of a huge EasMo-West Coast niigrotion that took 
place one heady summer many years ago. She 
stumbled upon o technicoi writing job and took 
to It and to California like a programmer to 
Mountain Dew, She^s been a programmer herself 
(ot Tymshore) and even o manager (at NeXT], but 


marks her favorite work yeors as those spent 
writing and editing at Apple — first Inside 
Macintosh and later develop. To keep herself 
sone outside of work, Caroline hos little do with 
computers and hos been known to stop making 
sense. She does, however, keep her wits honed 
for Scrabble. * 
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LETTERS 


NUMBER FORMATS FOLLOWUP 

Regarding the article ‘international 
Number Formatting” in drochp Issue 
16^ IVe written ResEdit editor 
(“FMAT Editor”) that enables you to 
easily create Script Manager canonical 
fonnats and store tliem as resources, I 
hope you'll find it useful, 

— Michael Hecht 

The anthfrr of the article looked at ymr 
editor, and he thought h was so useful that 
he sidmtitted it to the CD. Thanks! 

~ Caj-olme Rose 

NEW FLOATING WDEF ON CD 

Fm the author of a freeware floating 
window^ \\T)EF know n as the Infinity 
Wndoici. It was one of the first such 
WDEFs to implement the System 7- 
style coloring of windows, tinge colors 
and all. It includes support for a title bar 
down tJie left side of a window, System 
6’s coloring of windows, multiple 
monitors via DeviceLoop, and checking 
the available colors in 8-bit mode to 
deteniiine w'heiher the title bar should 
be colon 

I recently finished up version 2.5.1 of the 
W'DEF, W'hich adds the ability to hav^e a 
grow box, a tide string in the tide bar, 
and a slightly different style of tide ban 

Please consider including this \\T)EF 
with sotirce code on your CD, An 
appropriate place for it would be with 
Dean Yu's floating window^s code (Issue 
15), Dean has stated that his \\T>EF is 
not highly robust, and providing my 
Wl^EF with the source would make a 
lot of sense. This w^ould also help me 
meet my goal of making it available to 


as many Macintosh developers as 
possible, 

— Troy Gaul 

Thanks for hringmgyour H^DEF to our 
attention. IVe've included it with Issue / Ji 
floating windows code an this issuers CD. 
Dean has also mraked the code again since 
his last updates. Check it out! 

—^ Caro/me Rose 

GREAT MAG, BUT LOSE LEDGE 

My vote for your View From the Ledge 
column is: lose it! Dilbert (the comic 
by Scott Adams) does a much 
better job at commenting on the 
political and social .structures of 
corporate America, 

Thanks for the fine publication, deifelop 
is the only periodical that doesn't end 
up in the trash alter I read it. Keep up 
the good work, 

— Dave Lamkins 

The editor thanks you for your kind words 
about develop. As the author of View 
From the Ledge., Pve been volunteered to 
address your reinarks about that column. 

Scott Adams Ls unquestionably a genius. He 
biu: a certain wit and control of the English 
language that hasn't really betm equaled 
since Shakespeare^ atid an a7ristk flair that 
Tm retrain 'makes all Florentines weep. 
There's simply m way I can cotnpete with 
this caliber of raw talent. 

No doubt Mr. Adams gets invitations to 
dine with the President. Pve nev€t‘m€t any 
of the Presidents of Apple, let alone of the 
United States — although Joh?i Sadley did 
pull up next to me at a stoplight a few years 


DONnr FORGET TO WRITE! 

We welcome Mmely letters to the editors, 
especially From readers reacting to articles that 
we publish in develop. Letters should be 
oddressed to CorolEne Rose (or, if technical 
deve/oprefoted questions, to Dove Johnson) at 
Apple Computer, Inc,, 20525 Morionj Avenue, 


M/S 3034Dn Cupertino, CA 95014 
(AppleLink CROSE or JOHNSON.DK) . All letters 
should include your nome and company name as 
well os your address and phone number Letters 
may be excerpted or edited for clority (or to 
make them say what we wish they did).* 
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and I used To have aJean-Louis Gasse'e 
mask hanging in my rubkh. 

Mr. Ada?ns has the advantage of dealing 
with a world where the characters are two- 
dimensionaly all of their wo‘^‘st traits are 
brought to the forefrmit, and the situatmis 
these character's get caught up in border on 
the absurd. None of those things can be said 
about the real office environment. 

Having said all that^ we're putting View 
From the Ledge on ice after this issue^ and 
the thaw comes only if there'^sa chinook in 
thefonn of a strong reader response. 

—■ Tao Jones 

MISSING CD? A ROYAL PAIN 

First, Fd like to say that I think develop is 
excelleoL I await each issue with 
frenzied anticipation and find each one 
absorbing, infomiative, well written, 
and funny. 

rd also like to comment on the 
Bookmark CD, I can*t, however, 


because we don't get it, I keep reading 
articles referring to ^Miis issue's CD” 
and it’s infuriating! We get our regular 
monthly Developer CD with Apple 
Directions but no develop CD. Is this 
because we’re in England? Don't you 
like us any more? It's the royal family's 
fault, isn't it? They Ve made us took 
stupid. They’re nothing to do with us, 
honest. We'd just like our CD. 

—Richard Gibson 

Some international developers receive 
develop without the Bookmark CD as part 
of a mailing that includes the Developer 
CD and Apple Directions. Anyone who gets 
the Developer CD doesn't need the 
Bookmark CD (see ^^This issue's CD" on 
the inside front covef*). 

We still like our British readers^ so frtrm 
our standpoint you should have no gripe 
with the royal family. 

Thanks for wiiting! 

—Caroline Rose 


Do you yearn for the adulation of your colleagues? 



YOUR NAME HERE 


Yearo no more: write for develop. We're always looking for people 
who niight be interested in submitting an article or a eulunin. If 
you’d like to spotlight and distribute your code to thciusands of 
developers of Apple products, here's your opportunity. 

If you’re a lot better at writing code than writing articles, don’t 
woTTy. An cdittjr wall work with you. The result will be something 
you’ll be proud to show' your colleagues (and your Mom). 

So don't just sit on those great ideas; feel the thrill of seeing them 
published in develop] 

For Author’s Guidelines, editorial schedule, and infonnation on 
our incentive program, send a message to DEVELOP on 
AppleLink, dcvek)p@applelink.apple.com on the Internet, or 
Caroline Rose, Apple Computer, Inc., 20525 Mariani Avenue, 
M/S 303-4DP, Cupertino, CA 95014. 
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A re there issues of develop tliat have passed you by? If you\! like to cfimplete yom- develop collection^ 

. full-color, bound copies are available, (Back issues are also on die develop Boohmrk CD and tlie 
Reference Library edition of the Devdoper CD Series.) 

To order printed back issues, send $13 per issue in the (or $20 outside the U.S.) to develop Back Issues, 
RO. Box S3 i, Mount Moms, IL 61054-7858, Or call L800-877-S548 in the U.S, or (815)734-1116 elsewhere. 
Supplies mv Imiited. Please allmv 4 to 6 weeks jor delkmy. 
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Giving Users Help With Apple Guide 


A positive user experience means getting the task done with a 
minimum of hassle. But as applicatiom engage in the features race, 
their complexity mcreases as well, leading to increased user frustration. 
One solution is to add^ a powerful help system that can guide the user 
through a task. The new Apple Guide ^stem makes this chore easier 
than you might think. 



JOHN POWERS 


Someone Was decided that your application need*^ help. Maylje it’s a little heavy on 
the features, and Marketing is afraid that the user Mali l>e overwhelmed. Perhaps your 
user studies have shown that users can really benefit from some coaching w^hen 
learning your interface. Or the finance experts have figured out that you can save a 
lot of money on printing and user support costs by putting help on the screen rather 
than in printctl manuals. And yesterday the CEO declared that your product must 
Min a gold medal in customer satisfaction. 

It can he done. 

This article tells you how' to add Apple Guide, a new kind of help system, to your 
application with a pain and suffering level that you can control, ranging from almost 
nothing to only a tingle. 


d'he article doesn^ tell you w'hat help your application should provide; Uiafs up to 
your software designer, technical WTiter, instructional designer, interface designer, 
and M'hoever else likes to stir the design pot. Once youVe decided wdiat help you 
want and the technical writer has written it using the Apyde Guide authoring tool, 
you integrate it. That’s w^here this article-— and tin is issue’s C]D, which contains a 
sample program with Apple Cmide integrated —comes in. 


WHAT IS APPLE GUIDE? 

Apple Guide is a new kind of help system that acts as an interactive, task-oriented 
guide and Mill be available to all applications systemwide as of System 7.5. Apple Guide 
is based on more than two years of research on people’s need for help m bile using 
their computers. Several key findings of this research iindertie the Apple Guide design: 


JOHN POWERS [AppleLink JOHNPOWERS), 
MWM, Apple employee, seeks inlense 
reloffonshEp with soFtware. Enjoys object-orientied 
design, craFtsmanship, ciossical music, long 
walks, quiet moments, bser discs with popcorn, 
travel, engoging novels, and kinky polymorphism. 
Software must be willing to shore time with 
extended Family Documentation a must.* 


The Apple Guide Developer's Kit will soon 
be available from APDA (if it isn't already). It 
contains everything you need to outhor databases 
and integrote Apple Guide. Included in this kit is 
an outhoring tool that compiles help content 
written with o standard word processor into an 
Apple Guide database file. The kit also contains 
sample help content files and documentation.* 
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• Users are task-oriented, 

• Users seek help when they’re frustrated doing a task, 

• Help should be an interactive guide to accomplishing a task, not a 
static document. 

The paradigm is simple: 

L The user has a task to accomplish, 

2. The user becomes frustrated when an obstacle prevents 
completion of the task, 

3, The user asks for help. 

Traditional help requires users to go to a printed or on-screen document to identify 
the problem in the context of the documentation. This in itself can become a 
frustration. Users would rather have someone (or something) guide them through the 
obstacle. That’s what Apple Guide does: it acts as an interactive, task-oriented guide. 

Wlien users ask for help, the first thing they see is the access -wmdoWf which provides 
three ways of selecting the help topic. Once the user selects the help topic, the access 
window is replaced by the presentation windtrw^ which presents the help topic as a 
series of panels containing text, graphics, QuickTime movies, and controls. {Note 
that in an application in which Apple Guide has been folly integrated, the help topic 
can be preselected for the user based on context — more on this later.) To experience 
Apple Guide for yourself, try out the application called MoGuide on this issuers CD. 

Apple Guide is implemented as a system extension (see “What Systemwide Help 
Means” for some ramifications of this) that uses a guide database file to drive its 
interaction viith die user, as depicted in Figure I, The database file, written using the 
Apple Guide authoring tool, contains multimedia help content and instructions on 
how to interact with the user. The delivery engine is in the sj^tem extension, which 



PresenfoNon window 


Figure 1. How Apple Guide works 
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WHAT SYSTEMWIDE HELP MEANS 


Because tfs implemented as a system extension^ Apple 
Guide is available to all applications systemwide. It's 
designed to help users within and across application 
boundaries. Apple Guide can guide a user through 
multiple applications including^ but not limited to, the 
application that invoked it 


Apple Guldens systemwide nature has romiFicotions for 
everything you do with it. While it enables delivering an 
unprecedented level of help to users, it also presents 
certoin programming challenges. Consider the following 
characteristics of systemwide help and what they mean to 
you Qs Q developer. 


Help works across multiple applications. Your 
application's guide databose con guide a user through 
multiple opplications, not just your own. You can provide 
help for tasks that involve system-level operations and the 
use of other applications. 


One romification of this is that If the user switches from 
your application to another one after starting up Apple 
Guide ond without quitting your application or Apple 
Guide, Apple Guide will still be present and showing 
your guide database. This may be desirable, depending 
on what help you're providing. If not, the user can quit 
Apple Guide from the help window. Don't force Apple 


Guide to quit when your application goes to the 
background. 

Help is always availoble to the user. Your 
application can olways invoke Apple Guide, even if it's 
in use by another opplicatlon. That application's guide 
database will be closed and yours will be opened ond 
shown instead. 

This works the other woy around os well — if the user 
invokes Apple Guide from the Help menu within another 
application while yours is open in the background, your 
guide database will be dosed and the other application's 
will be opened and shown instead. Moreover, the other 
application can still moke Apple Guide quit even if you 
closed Its guide database to show your own. 

The bottom line for you is that you can't ossume that your 
guide database is always open, even if the user invoked it 
from within your application. A call for dealing with this is 
described later, under "Is Your Guide Database Open?" 

The user is alwoys in control* Users can quit Apple 
Guide at any time, even if they've switched from the 
application that storted it up. Once again, this means that 
you can't assume your guide database is alwoys open, 
even If the user invoked it from within your application. 


contains two components: a stay-resident portion and a laiinch-as-needed application 
portion. With a RAAl footprint of less than 2OK, the stay-resident portion installs 
patches at startup time^ mamij^es the Help menu (the one labeled with a question 
mark in a halloon), and starts up Apple Guide from the Help menu. The application 
porti«)n is loaded and run when help is being delivered; with a Ri'\At footprint of 400K, 
it’s launched as a faceless background application in its own heap. The Apple Guide 
system extension and several guide databases will be provided as part of System 7.5. 

TO INTEGRATE OR NOT TO INTEGRATE? 

You can put Apple Guide to work for you whetlier or not you decide to integrate it 
into your application. However, as in life, the level of pain you choose determines the 
amount of gain. 

The easiest way to add Apple Guide to an application is to place an Apple Guide 
database file in the same folder as the application. No coding changes are necessary; 
the integration is automatic. The Apple Guide extension adds the database to the 
application’s Help menu and launches the database when the user chooses it. 

Here’s what Apple Guide delivers without any changes to your application: 

• help initiated from the Help menu 

• interactive delivery of multimedia help content 
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• the ability to mark static interface objects, or dynamic interface 
objects identified using the Object Support Library^ (OSL), to 
draw the user’s attention to them 

• elementary to intermediate context sensitivity 

This is a lot of help in itself But if you want more control over Apple Guide, you'll 
need to make code changes in your application. Here's what those changes can add: 

• information about where the user is in the help system 

• mc^re direct control over what help the user receives and 
responsiveness to the user’s context 

• help initiated from any control — including buttons, lists, and 
special keys — and from application menus 

• guide databases with your own creator, type, and document icons 

• the ability^ to use databases located in a folder separate from the 
application 

If you want the gain and youVe ready for the (slight) pain, read on. 

To communicate w ith Apple Guide from your application, you use standard, trap- 
based funetion calls. The function calls enable your application to get information 
about Apple Guide, start up Apple Guide, respond to Apple Guide, modify help 
content, and quit Apple Guide. Fll explain how' to do each of these in the sections 
that follow. You might want to examine die source code for the sample program 
MoGuide on this issue’s CD to see die function calls used in context. Then you can 
try integrating Apple Guide into your own application. 


GETTING INFORMATION ABOUT APPLE GUIDE 

Your application can find out a nuniber of different things about Apple Guide: 
whether it’s installed, w^hat its status is, whether an xAppIe Guide database is available, 
the number and characterisDcs of guide databases available, and w^hether your own 
guide database is open, 

IS APPLE GUIDE INSTALLED? 

Before you do anything with the Apple Guide extension, you need to determine 
whether it’s installed. The following code show's how: 

long reault^O; 

OSErr err = Gestalt(gestaltHelpHgrAttr, ^result); 
if (err==noErr && ^result & (1 « gestaltAppleGuidePresent))) 

; // Apple Guide is available, 

else 

; // Apple Guide is not available. 

WHArS THE STATUS OF APPLE GUIDE? 

Once you’ve determined that Apple Guide is installed, you can get more information 
about its state — for example, is it active (displaying a help window)? If it is, which 
help window^ is being displayed? The latter infonnation can be saved and used to 
restart users at the point w^here they left the help system. 

The xACiGetStatus function returns whether Apple Guide is active (kAGIsActive), 
sleeping (kAGIsSleepmg), or not running (kACilsNotRunning). In the active state. 
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help is being provided (a guide database is open). In the sleeping state, the Apple 
Guide background application is loaded and running, but no help is being provided 
(no guide database is open). In the not-ninning state, the application portion of Apple 
Guide isn’t loaded or running. 

If Apple Guide is active, you can further determine whether the access window or the 
presentation window is showing. For example: 

if {AGGetActiveWindowKind( j^kAGAccessWindow) 

; // Apple Guide access window is showing, 

else if (AGGetActiveWindowKind()=^kAGPresentationWindow) 

; if Apple Guide presentation (topic) window is showing, 
else 

? //No window is showing; Apple Guide is sleeping or not running. 

Be sure youVe determined that Apple Guide is installed before invoking 
AGGetStatus or any odier Apple Guide function. Otherwise, if Apple Guide isn't 
present, you’ll get an unimplemented trap error. 

IS AN APPLE GUIDE DATABASE AVAILABLE? 

You can find out whether an Apple Guide database is available to die current 
(frontmost) applicadon, and furthermore, whether a specific type of guide database is 
available. ('I'liere are two file types and five database types, classified according to the 
type of help information they contain; see About Apple Guide Database Files" for a 
rundown of die types.) 

The AGGetAvailablcDBTypes function returns bits set to correspond to the various 
types of guide databases available to (in the same folder as) die frontmost applicadon. 

enim AGDBTypeBit //To test against AGGetAvailableDBTypes 
{ 

kAGDBTypeBitAny = 0x00000001| 

kAGDBTypeBitBelp = 0x00000002^ 

kAGDBTypeBitTutorial = 0x00000004 1 

kAGDBTypeBitShortcuts = 0x00000008, 

kAGDBTypeBitAbout = 0x00000010, 

kAGDBTypeBitOther = 0x00000080 

The kAGDBlypeBitAny bit will be true if the application has any Apple Guide 
database file available. Thus, the following statement will test whether any guide 
database is available: 

if (AGGetAvailableDBTypes[} & kAGDBTypeBitAny) 

; // Some kind of database is available 

You can simlarly use the other constants to test the availability of specific types of 
Apple Guide databases. 

HOW MANY AND WHICH GUIDE DATABASES ARE AVAILABLE? 

The tests described in the preceding section apply only to guide database files or their 
aliases in the same folder as the application. You can also find files outside the 
application's folder, by using the AGFile library that's included on this issue’s CD. 

This library doesn’t use or require the Apple Guide system extension and offers 
access to information about Apple Guide database files. 
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ABOUT APPLE GUIDE DATABASE FILES 

Apple Guide dotabase files provide the content of the 
help that your application gives users. These files con be 
of the following two types: 

• IcAGFileMain: Moin or normal type of Apple Guide 
database file 

• kAGFileMixin: Mix-in dotabase file, which modifies a 
main database file with updates and additions at run 
time 

Files of both types have a creator of kAGCreator, which 
is 'reno*, and are further subdivided by database type 
according to the type of help information they contain. 

The database type is stored as part of the database 
content and determines where the file is represented in the 
Help menu, as indicated in Figure 2. 

Apple Guide supports multiple guide database files but 
only one of eoch type, except for kAGFileDBTypeOther. 

You can have multiple kAGFileDBTypeOther files; they're 
added at the end of the Help menu, ordered by filename. 

All Apple Guide database files located in the some 
folder os your application will be represented in the Help 
menu. [Note that aliases will work as well as database 
files themselves, but that folders nested within your 
application's folder will not be searched.) 


If you don't want a guide database represented in the 
Help menu, you should separate the guide database from 
the application. In this cose, you must provide a 
mechanism in your application to start up Apple Guide 
with that database, since the user can't do it from the 
Help menu. The section "Storting Up Apple Guide" tells 
□It about this. 

Databases can olso have your creator and type, ollowing 
you to use your own document icons. Databases 
identified this way won't show up on the Help menu and 
must be opened from your application. 


kAG F i I e D BTypeAbout 


kAGFileDSTypelutorial — 
kAGFifeDBTypeHelp —— 
kAGFileDBTypeShortcuts 

kAGFileDBTypeOther — 



Hbout Kelp... 


Shouj Balloons 


Tutorial 

Help dil 

Shortcuts 


Quicklook 


Figure 2* Menu items identified by database type 


Wth the AG File library, you can coiint and find guide databases of specific file and 
database types. Once youVe Found a database, you can get in forma don about it. For 
example, the following code counts the number of main guide database files (those 
that aren't mix-in files) of type kAGFileDBTypeHelp in a specified volume and 
directory: 


AG Fi1eC oun tType 

AGFileDBType 

Boolean 


guideFileCount; 

databaseType=kAGFileDBTypeHelp; 
wantMixin=false ; 


gu ide F i 1 eC oun t = AGF i 1 eGetDBCo u n t (vKe f tiun, dir ID, da t aba s eTy pe, wantMixi n ); 

You can get the FSSpec for a particular type of Apple Guide database file in a 
specified volume and directory as follows: 


AGFileCountType 

AGFileDBType 

Boolean 

short 

FSSpec 


guideFileC ount; 

databaseType=kAGFileDBTypeOther; 

waiitMixln=f alse ; 

dblndex=l; 

dbSpec; 


err = AGFileGetIiidDB(vRefl!lmn, dirlD, databaseTypef wantMixin, dbindex, 
fidbSpec); 
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The AGFileGetlndDB call will return noErr and the FSSfiec for the database file if 
it*s present* Increment dhindex to find additional guide databases of the same type. 


Listing 1 shows how to accumulate a list of FSSpecs for all the guide databases in a 
specified volume and directory. 


Listing 1 , Accumulattng FSSpecs for guide dotoboses 


AGFile Count Type 
AGFileDBType 


Boolean 

FSSpec 

Bandle 


guideFileCount; 

databaseType=kAGFileDBTypeAny ; 
wantMixin=false; 
dbSpec; 
hFileList? 


// See how many guide files are available. 

guideFileCount = AGFileGetDBCount( vRefNuirif dir ID ^ databaseType, 
wantMixin); 

if (guideFileCount>0) { 

// Create a new list of file FSSpecs. 

hFileList = NewHandle(guideFileCount * sizeof(FSSpec)); 

if (hFileListI^nil) { 

// Get each file and add to list. 

for (short i~l; i<^guideFileCount? i+t) { 

if (AGFileGetlndDB(vRefNmn, dirlD^ databaseType, 
wantMixin^ i, &dbSpeG)==noErr) { 
({FSSpGC*)(*hFileList))[i-l] = dbSpec; 

> // if 

} // for (short... 

} //if (hFileList... 

} //if (guideFileCount... 


Once you have the FSSpcc for a database file, you can ask for more information. For 
example, the following ccjde can be used to get the version and menu item name for a 
database: 

AGFileMajorRevType majorRev; 

AGFileHinorRevType minorRev; 

S tr 2 55 me nuName; 

AGFileGetDBVersion(&fileSpec, smajorRev, aminorRev); 

AGFileGetDBMenuName(sfileSpec, menuKame); 

IS YOUR GUIDi DATABASE OPEN? 

/\s mentioned earlier in “Wliat Systemwide Help Means,” you can^t assume your 
guide database is always open, even if the user invoked it ifom within your 
application. To cope with this fact of life^ your application should call the 
AGIsDatabaseOpen function whtn it’s switched fi’om background to foreground, 
passing in the database’s reference number, to see if its guide database is still open, 

if (AGIsDatabaseOpen(myAGRefNum)} 

; // The database with myAGRefNum is open, 

else 

; // The database with myAGRefNum isn’t open; someone else closed it. 
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If AGIsDatabaseOpen is true, you can also assuoie that Apple Guide is active. If 
AGIsDatabaseOpen is false and you haven't explicitly closed your database, another 
application or the user has closed it. 

STARTING UP APPLE GUIDE 

You can start up Apple Guide with either the first available guide database or one you 
specify. You can also control the initial view the user sees, choosing firoin seven 
different options. In this initial view you can present the user with a list of topics 
related to die context, or you can skip the initial view and instead take the user 
directly to a help topic. 

DEFAULT STARTUP 

The default startup, the quickest and easiest way to start up Apple Guide, opens the 
first available guide database. The database must be in the same folder as your 
application (the Finder is an exception — its guide databases are in the Extensions 
folder), ITe mechanism is similar to what happens when the user selects an item 
from die Help menu. 

The default startup is accomphshed by calling the AGOpen function with the 
kAGDefault flag: 

err - AGOpen(kAGDefaulty 0, nil, SiniyAGRefnum) ? 

A reference for die database that was opened is returned in myAGRefNum. You must 
use diis reference when you close the dataliase, 

Apple Ciuide starts up with the frontmost application's guide database and the startup 
conditions specified in the database. If more than one Apple Guide database is 
available for the application, the first database of type kAGFileDBTypeHclp is used. 
If no database is present, the error code k ACt Err D a tabaseNot Avail able is returned 
and Apple Guide doesn't start up, 

DATABASE OTHER THAN THE DEFAULT 

An appliaition can also open a specific guide database when it starts up Apple Guide, 
by specifying the FSSpec for the database in the AGOpen call: 

err = AGOpen (&myGuideDatabaseFSSpec^ 0^ nil^ SiinyAGRefHum); 

See the earlier section Many and Which Guide Databases Ai’C Available?” for a 

suggested way to get a database FSSpec. 

VIEW OTHER THAN THE DEFAULT 

Apple Guide offers seven startup view options. This is riormally controlled by the 
guide database; however, these defaults can be overridden with a startup function 
parameter. For example: 

err = AGOpenWithView(£(inyGuideDatabaseFSSpec ^ 0, nilp kAGViewIndex, 

&niyAGRef Mum ); 

Six of die possible startup views are listed below. These views, w^hich are access 
windows, are shown in Figure 3. Startup view number 7 is the topic or presentation 
window view, which is started with a different function call (described below in 
‘‘Going Directly to a Topic”). 
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View 1: Full-window howdy 



View 2: Full-window lopic areas 



View 3: Full-wfndow index terms 
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Figure 3. Six startup view options 


enum 

{ 

kAGViewFullHowdy = 1, 

kAGViewTopicAreas = 2 , 

kAGViewIndex = 3, 

kAGViewLookFor = 4, 

kAGViewSingleHowdy = 5, 

kAGViewSingleTopics = 6 


// Full-window howdy 
// Full-window topic areas 
// Full-window index terms 
// Full-window look-for (search) 
// Single-list howdy 
// Single-list topics 


Since almost all guide databases contain multiple topic areas, they usually start up 
with the kAGVtewFullHowdy view. If you specify a L\GViewSingIeHowdy or 
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kAGMewSingleTopics view for these kinds of guide databases, only tlie topics for die 
first topic area will be shown, 

PRIMING A SEARCH 

An applicarion can start up Apple Cruide (or restart it if it’s already running) in the 
look-for view with a list of context-sensitive topics that match a search string (a 
Sti255). To ini date a con text-sens id ve search, use the AGOpenWithSearch function 
and include a look-for search string as fbllows: 

err = AGOpenWithSearch{&myGuideDatabaseFSSpec, 0, nil^ mySearchString^ 
&myAGRefKiun); 

GOING DIRECTLY TO A TOPIC 

Sometimes you may w'ant to inidate help wdien the user clicks a Help button in a 
dialog or Option-clicks an interface object. In these cases, you have a good idea of the 
context and can bypass the Apple Guide access window, going directly to the 
presen tad on window w^ith die selected help topic. Here’s how: 

err = AGOpenWithTopic(&myGuideDatabaseFSSpec, 0, nili myTopicId, 

&myAGRefNuni); 

The presentation window will appear with the first panel of the topic. 

The Apple Guide authoring tool usually handles topics by name and quietly assigns a 
topic ID number w hen the database is compiled. However, you can override this 
automatic assignment by specifying your own topic ID, See the authoring tool 
documentation for information on how to assign your own topic ID numbers. 

RESPONDING TO APPLE GUIDE 

The author of an Apple Guide database file can initiate a number of different kinds of 
events to which your application may need to respond. These include attaching Apple 
events to controls in help topics, drawing coach maj-ks on dynamic interface objects, 
sending Apple events when certain panels appear, and using context checks to 
determine whether a presentation panel should he shown or skipped. 

RECEIVING THE AUTHOR'S EVENTS 

A help author can attach an Apple event to any control in an Apple Guide 
presentation window. The controls can be Macintosh buttons, checkboxes, radio 
buttons, or Apple Guide buttons (the last two types of controls are illustrated in 
Figure 4). The author s action specification for these controls will contain 

• the target for the action (usually an application signature) 

• the Apple event class 

• the Apple event ID 

• the optional key 

• optional data for the optional key 

The action might be directed to Apple Guide — for instance, to start up another 
presentatitjn window, to return to die access window, or to go to another panel in the 
same topic. The action can also be directed to your appheation; in that case, the 
target is your application signature, and the Apple event class and event ID are ones 
for which youVe installed a handler The content of die optional key/data field can be 
anyirhing; how^ it’s used is up to the application developer, Apple Guide extracts the 
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Apple Guide buttons 


Figure 4, Controls in a presentation window 


optional data fields calculates its size in b}aes, calls iAEPutParamPtn with a descriptor 
type of typeChar, and sends the Apple event. 

To receive the action, install an Apple event handler for the class and event ID. Your 
handler can get the optional data parameter using your key. 

There is no reply to this event. If you want to reply, see the section “Responding to 
C>ontext CChecks.” 


PROVIDING ORJECT LOCATION FOR COACH MARKS 

Coach marks are circles, X’s, underlines, and arrows that can be drawn on interface 
objects to direct the user’s attention to them, as illustrated in Figure 5- Using such 
marks has been shown in tests to be niiich more effective than putting drawings of the 
objects into the help content (users tend to click on the drawing, not the real thing). 
The Apple Guide authoring tool provides a fairly complete set of instructions to 
mark many common interface objects, such as the following: 

• menu titles and items 

• windows and any coordinates relative to a window 

• window^ elements such as close boxes, size boxes, titles, and scroll 
bars 

• items that have a help balloon “hot rectangle’^ 

• dialog items 

These are all relatively static elements with locations that can be found by Apple 
Guide’s marking facility. Some interface objects, on the other hand, are dynamically 
located at locations known only to the application. If youVe identified a dynamic 
interface object using the Object Support Library^ (OSL), you can use Apple Guide’s 
built-in OSL coach-marking facility to locate and mark the object. See the 
documentation for the Apple Guide authoring tool for details. 

If you want to mark dynamic interface objects and you’re not using the OSL, Apple 
Guide provides another method for you to use. In tiiis method a handler installed by- 
Apple Guide calls your application asking for the rectangle of a named object. To use 
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Figure 5* Cooch marks 

this tnethod, your application must install a coach handler that takes the object name 
and replies with the object rectangle in global coordinates. 

Here’s an example. First, you install the coach handler: 

AGCoachRefNum inyAGCoachRefNum; 

OSErr err = AGInstallCoachHandler{MyCoachReplyProc, myRefCon, 

SmyAGCoachRefMum ); 

The protot>Tie for a CoachReplyFroc is as follows: 

typedef pascal OSErr {^CoachHeplyProcPtr) (Rect* pRect, Ptr name, long refCon); 

Apple Guide will invoke your CoachRcplyProc witli die name (a null-terminated C- 
siring) and myRefCon from the AGInstallCoachHandler call. Set the value of pRect 
to the object rectangle in global coordinates. The following is an example of a 
CoachReplyProc* Apple Guide wiU draw die coach mark aromicl, under, or through 
the rectangle provided in die reply. 

pascal OSErr HyCoachReplyProc{Rect* pRect, Ptr name, long refCon) 

{ 

// Look up the name and return the rect in global coordinates, 

OSErr err = MyRectForName(pRect, name)? 
return err; 

} 

Coach handlers persist across the opening and closing of guide databases. However, 
you must remove the coach handler when your application quits. Use the 
AGCoachReflSTuni that was returned to you in the AGInstallCoachHandler call. 

OSErr err = AGRemoveCoachKandler(&myAGCoachRefNum); 

RESPONDING TO THE USER'S HELP FOCUS 

You can get Apple Guide to notify your application whenever a particular panel is 
being displayed (in other words, whenever it’s the user’s help focus) by taking 
advantage of Apple Guide’s autliorable actions. To do this, use the authoring tool to 
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attach an Apple event of your choosi ng to an “ On Panel Show” or “On Panel Hide” 
action. V\Tien the panel is shown or goes away, the Apple event is sent to your 
application, wliich can then respond appropriately. For example, it might be useful to 
attach an Apple event to an “On Panel Shov^” action for the last panel in a series of 
insmictions, to signal that the user has reached the end. See the authoring tool 
documentation for infonnation on how to attach an Apple event to a panel action. 

RESPONDING TO CONTEXT CHECKS 

Apple Guide can use context checks to get information about the user^s environment 
and, based on that, to decide which panels to show in a presentation window. This 
enables the Apple Guide author to tailor the help to the user^s current context. It 
gives an individualized feel to the instruction and avoids requiring the user to 
navigate through irrelevant information, things that users appreciate a lot. WTen you 
integrate Apple Guide, the user’s context will usually be your application. The help 
author will want to use information from your application to determine what help the 
user needs. You’ll need to respond to these context checks by installing an Apple 
event handler, processing the context check, and returning true or false. 

I lere^s how it works: author attaches conditions to selected panels. These 

conditions can be based on context checks or on user controls in other panels. \ATile 
die user is reading the content of a presentation window, Apple Guide looks ahead to 
see which panel to show next. It evaluates the conditions, including context checks, 
attached to each panel. \^Ten Apple Guide evaluates a context check, it invokes the 
Apple event handler for the context check. The restiks of the evaluation based on the 
context check determine whether the pane! should be shown or skipped. 

Context checks are usually encapsulated as Apple Cmide “external modules” and 
attached to a database. An external module is a code resource that executes in response 
to the query from Apple Guide. Creating and using external modules is outside the 
scope of this article, but see the TContext::ReplyToContext function in the sample 
code for an example of how to handle context checks From within your application. 

Apple Guide handles context-check queries similarly to coach-mark queries. You 
install a context-check handler and Apple Guide calls it. First, the installation of the 
handler: 

AGConte xtRe fRum myAGC o n t e xtRe f Hum ; 

OSErr err = AGInstallContextHandler{HyContextHeplyProc, eventID, myHefCon, 

&niyAGCoiitextRefHum); 

The prototjqDC for a CkjntcxtReplyProc is as foUows: 

typedef pascal OSErr {^ContextReplyProcPtr)(Ptr plnputData^ 

Siae inputDataSize, AEEventID eventId, 

Ptr *ppOutputData, Size *pOutputDataSize, 
long refCon); 

WTen Apple Guide needs to do a context check, it invokes your callback with the 
context-check inputData and evendd. It also passes the refCon that you provided in 
the AGInstallContextHandler call. The ContextReplyProc should use NewPtr to 
create a storage area for a short, set *ppOutputData to the value of the pointer, and 
set *pOutputDataSize to sizeof(short). Always return a pointer to a short Apple 
Guide will dispose of the pointer. 

You Ye probably wondering why w^e didn’t pass a Boolean instead of *ppOutputData 
and *pOutputDataSize. The reason is that the context reply is a special case of a more 
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g-eneral reply mechanism, which Fm not going to go into here. Just take my word for 
it — it has to be this wav- 

Context handlers persist across the opening and closing of help databases. However, 
you must remove the context handler when your application quits. Use the 
AGContextRefNum that was returned to you in the AGInstallContextHandler call. 

OSEr r err = AGRemave Con tex tHa nd 1 er (SmyAGCon te xtRe f li uia) ? 

If you just want to field Apple events that don't require a reply, see the earlier section 
^Receiving the Author’s Events.” 

MODIFYING HELP CONTENT 

So far, weVe talked only about main guide database files, the standalone files that 
support all or part of an application. You can modify the content of a main guide 
database by mixing in a mix-in guide database. 

When a field upgrade involves new features and you don’t want to release a revised 
guide database, you can use x4pple Guide’s mix-in files to add help content to the 
main guide database file. The mix-in files don’t appear in the Help menu. \4Ten 
Apple Guide starts up, each mix-in file is merged with a main guide database file of 
the corresponding DB'Iype. iMultipIe mix-in files can be mixed in. 

The process is automatic, but the guide database author can control it by using 
Gestalt selectors. Each guide database file contains three Gestalt selectors. The 
selectors must evaluate to true in order for a main database to appear in the Help 
menu or a mix-in database to be mixed in. The Gestalt selectors in a given file are 
combined using Boolean OR logic. Empty Gestalt selectors are ignored. If all Gestalt 
selectors are empty, the file is unconditionally accepted. 

There’s a really cool way for the programmer to handle this. If the first Gestalt 
selector is the literal ’QLfy\ Apple Guide will call a code resource of t^^e 'QLfy' in 
the database file. If the code resource returns true, the database file will be mixed in; 
if it returns false, it won’t be. The prototype for the code resource is as fidlows: 

short(*QualifyFuncType)fvoid); 

The AGFiie library described earlier provides accessor functions that you can use to 
get the selectors and their values from any database. Only the authoring tool can 
change the selectors, however 

QUITTING APPLE GUIDE 

When you’ve finished using a guide database, use the AGCIose function with a 
pointer to the AGRefNum for the database, 

err = AGCIose (&niyAGRef^Juin) ? 

This will close the database and leave Apple Guide running in die background. Wien 
you’ve finished with Apple Guide, use the AGQuit function. 

err = AGQuit(); 

This will make Apple Guide quit. If you attempt to call AGQuit without first closing 
the database, you’ll get a kAGErrDatahaseOpen error. 
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If you start Apple Guide from your application, you should make it quit Otherwise, 
the Apple Guide background application and help window will hang around without 
your application and consume system resources. This persistence is a result of the fact 
that Apple Guide is available systemwide. Even if the user quits Apple Guide by 
clicking the Cancel button or the close box, you must still baiance every AGOpen 
function with an AGClose. 

STEPS TOWARD INTEGRATION 

Now you know what’s involved in integrating Apple Guide into your application. If 
you’re starting with a new product, you can build the use of Apple Guide into its 
design from die beginning; diis can provide you with a competi tive edge. If you Ve 
re'V'ising an existing product, you can add Apple Guide as a key feature. In either case, 
the instructional designer or technical writer should work closely with the software 
engineers to include an interactive task-oriented guide as an integral part of the 
design. Here’s a suggested plan for doing that: 

L The instructional designer prepares a specification for how the 
application, Apple Guide, and the paper documentation will work 
together. The specification should include a description of the 
information that the guide database needs from the application 
and vice versa — for example, how' help is started, Apple events, 
context checks, and coach-mark locations. 

2. The sofware engineers use the instructional designer’s 
specification to add the necessary Apple Guide features to the 
application, 

3. The instructional designer autiiors the database. 

4. The use of the guide database is included in the application’s test 
suite. 

PUTTING IT ALL TOGETHER 

It’s up to you and your database author to a.sseiiihle Apple Guide’s features into useful 
and cohcTeot help for your user. Tliis section gives some suggestions lor making 
Apple Guide as helpful as it can he. 

MULTIPLE DATABASE FILES 

You should provide different guide database files for different needs, Apple Guide 
database possibilities include the following: 

• an Apple Guide “agent” that guides the user through a task 

• a tutorial to provide basic instruction 

• command reference 

• application shortcuts 

• databases that match the user’s level of experience 

• a “here’s what’s new in this release” database instead of a read-me 

file (Marketing will love it!) _ 

HELP EVERYWHERE YOU NEED IT 

Your user should have access to help under all conditions. Here are some possibilities: 

• from the Help menu 

• from a help button in your tool palette 
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• from 3 help button in your modeless alerts and dialogs 

• from a help hf)t key, enabling the user to click an object and bring 
up a relevant help topic 

CONTEXT SENSITIVITY 

You, too, can use the buzzword ‘^context sensitive,” Use the Apple Guide features to 
provide “smart” help — help that^s tailored to the user^s current context: 

• Start up Apple Guide in the look-for view with a list of context- 
sensitive topics. 

• Bypass the access window^ and go directly to the presentation 
window^ when the user initiates help from a controk 

• Respond to the guide database author's context checks. 

• Selectively mix in database content. 

INTERACTIVITY 

The built-in features of Apple Guide provide a high degree of interactivity. You can 
provide even more with integration: 

• Identify dynamic interface olijects with coach marks. 

• Have Apple Guide notify you w^hen the user is at a particular help 
panel (the help focus) so that your application can respond 
appropriately. 

• Have your help database author add user controls that send Apple 
events to your application. Use them to allow the user to interact 
with you. 

NEXT STOP, GOLDEN MASTER 

This article has covered the basics of how your application can integrate Apple 
Guide. There’s more in the complete API, but you have enough here to get started. 
With or without integration, the help system is there to serve your user. It shouldn’t 
be compensation for bad interface design, nor should you add it just to save money 
on manuals or user support. Help is there to make your user more productive with 
your product, leading to a positive user experience, lots of recommendations, and 
sales, sales, sales. 

It can be done. 


Thanks \o oyr lechnical reviewers Peter 
Commons, Winston Hendrickson, Josh jocobs. 
Dove Lucky Dave Lyons, and Eric Soldan. * 
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PETER HODDIE 


SOMEWHERE IN 
QUICKTIME 

Basic Movie 
Playback Support 


Adding basic QuickTime movie playback support to 
most applications is simple, often just one day's work. 
Developers who want to do this turn first to Imide 
iVIacintosh: QuickTime^ where it says to use a movie 
controller component. In Inside Macmtosb: QuickTime 
Compone?Jts, you find some elementary movie controller 
code samples, followed by a large reference section. 
This is usually enough to get started, but there are a 
few common problems. This column addresses some of 
them, with special attention to compatibility with 
future QuickTime releases. It assumes you're familiar 
with basic QuickTime and movie controller concepts. 


have a resource fork. Still, you can use the exact same 
sequence of calls, Wlien OpenAlovieFile is called, the 
file reference returned refers to the data fork; 
NewMovieFromFile loads the movie from the data 
fork, and CloseMovieFile closes the data fork. 

Some developers don't use OpenMovieFile; they use 
FSpOpenResFile instead. While this works fine with 
movies made specifically for the Macinttjsh, it fails 
miserably otherwise. There's a sample movie with no 
resource fork, QuickBuck, on this issue's CD, sc] you 
can test this situation with your applications. 

If you need to know whether OpenMovieFile opened 
the resource fork or the data fork, you can examine the 
file reference it returns, as follows: 

pascal Boolean IsDataFork:( short fileReference) 

{ 

F CBPBRec an FC B; 

Str63 fName; 

anFCBToVRefNum = 0; 
anFCBToRefNmn = fileKeference; 
anFCBToFCBIndx - 0; 
fName[0] = 0; 

anFGB,ioNamePtr = (StringPtr)fName? 


OPENMOVIEFILE 

All QuickTime movie files contain a movie resource, 
usually stored in the file’s resource fork, and tlie actual 
movie data, stored in the file's data fork. To support 
cross-platfonn QuickTime movies, QuickTime’s Movie 
'Iboibox also allows the movie resource to be stored in 
the data fork along with the movie’s data. {To learn 
how this is done, see Jolin M'^ang's Somewhere in 
QuickTime column in develop Issue 17,) The usual 
sequence of calls to load a QuickTime movie from a 
file is: OpenMovieFile, NewMovieFromFile, 
C^loseMovieFile. 

In the conuiion case of the movie resoiu’ce stared in 
the resource fork, OpenMovieFile returns a file 
reference to the resoui'ce fork of the movie file, 
NewMovieFromFile loads the niovde resource from 
that resource fork and creates a QuickTime movie, and 
CloseMovieFile closes the resource fork. 

But if the movie was created on a computer running 
Microsoft Mindows and QuickTime for Mfindows 
(using Adobe™ Premiere, for example), the file won't 


if (PBGetFCBlTifoSync(&anFCB) 1= noErr) 
return false; 

return {anFCfl,ioFCBFlags & 0x0200) == 0? 

} 

NEWMOVIECONTROLLER 

When you need a user interface for playing a movie, 
you should use NewMo vie Controller to create a movie 
controller appropriate For use with diar movie, 

A common mistake is to instead use the Component 
Manager routine FindNextComponent or 
OpenDefaultComponent to locate a movie controller. 
This finds the first movie controller in the system's list 
□f registered ccjiuponents, QuickTime has always 
contained only one movie controller, so this worked 
fine. However, future versions of QuickTime will 
almost certainly include other movie couB'Dllers, so the 
first one isn’t necessarily the most appropriate one. 

To help track dowm chose offending applications that 
don’t use NewMovieController, there's a system 


PETER HODDIE writes code to introduce hord-lo-ftnd bugs into 
QuickTime. In his spore time he writes code to Introduce even 
harder-ta-find bugs Into QuickTirrie. * 
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extension on this issuers CD which contains a different 
movie coiitrollen You’ll also find a movie, Other 
Controller Movie, should invoke the sample movie 
controilen If any other movie invokes the sample movie 
controller, or if Other Controller Movie invokes the 
standard movie controller, the application youVe 
testing isn’t using NewMovieControllen This will 
cause undesirable results in the not-so-distant future. 

UPDATE EVENTS 

If you use a movie controller in the recommended way 
(that is, you allow all events to be filtered through 
MCIsPlayerEvent), it updates all areas of the window 
covered by the movie and the movie’s controls. Usually 
that’s all a window^ contains, so all update events are 
completely handled by the movie controller, 'I'his 
works so well chat some developers actually forget to 
support update events at all. 

Unfortunately, it’s not always so simple, QuickTime 
movies aren’t always rectangular. If the movie is round 
and the window is rectangidar (as in Figure 1), there 
are areas in the window that are not covered by the 
movie or the movie controls, ^\ny update events in 
these areas are the responsibility of the appHcation. 



Figure 1. A nonrectangular movie 

For applications using MCIsPlayerEvent, handling 
update events is easy: 

BeginUpdate(theHindow)j 
EraseRect {&theWiridow->portHect); 

EndUpdate{theWindow); 

This sample code erases all areas of the window besides 
the movie and its controls. Normally, erasing the 
portRect of the window wimld erase the entire window, 
but MCIsPlayerEvent sets the update region to just the 
areas it didn’t already handle. 


If you don’t handle update events, things are even 
worse than you might think. The window w^on’t be 
updated correctly, but more important, the operating 
system will keep generating new^ update events. Update 
events have a higher priority than idle events, so the 
system will never generate idle events — the movie will 
receive no time to play. 

A sample round movie is provided on this issue’s CD so 
that you can test your handling of update events. 

KEYSTROKES 

The standard movie controller provides for extensive 
keyboard control from the user but ignores keystrokes 
by default. They can be enabled with a single Hne of 
code: 

MCDoAction(me, mcActionSetKeysEnabled, 

(void *)true); 

You might want to enable keystrokes only under 
certain circumstances. For example, a word processor 
might alhjw the nio%de controller to receive keystrokes 
only when a movie is selected. You can use the 
mcActionSetKey sEnabled action to enable and disable 
keystrokes as necessary. 

MOUSE CLICKS 

All applications that use the standard movie controller 
pass mouse clicks on to the controller. But not all 
applications pass mouse clicks made on the movie itself. 
Failure to pass such clicks will cause problems with any 
Ihture movie controllers that allow' the user to interact 
directly with the contents of the morie. For example, a 
movie controller might allows the user to pan around 
the image by dragging on the movie; if mouse clicks 
aren’t passed through, using either MCClick or 
MCIsPlayerEvent, this feature won’t work. 

MOVIE CONTROLLER HELP 

The standard Apple movie controller is simple enough 
for most people to understand itmiiediately, but it 
supports help balloons anyway (future movie 
controllers might be less obvious). If Balloon Help is 
turned on, the standard movie controller automatically 
displays help for its various controls, as well as for the 
QuickTime movie itself. You don’t have to do anything 
at all for this to w^ork. 

A problem can arise if your application puts up its own 
help balloons. Since QuickTime mories are often 
embedded in a larger document, the help balloons may 
conflict. The result is that the movie controller’s help 
balloon alternates with the application’s help balloon. 
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(Use Balloon Help with the Scrapbook desk accessory 
included with QuickTime to see what this looks like.) 

The preferred solution is to stop the application from 
displaying a help balloon when the cursor is over a 
QuickTime movie or movie controk It’s easy to tell 
whether a given point in a window^ intersects the movie: 

Boolean Poin11nMovieContro11er(HovieController 
me, WindowPtr w, Point vhere) 

{ 

RgnHandle rgn? 

Boolean result = false; 

rgn - MCGetWindowRgn(mc, wj; 
if (rgn nil) { 

result = PtInRgnfwhere, rgn); 

DisposeRgn(rgn); 

} 

return result; 


CURSOR SHAPE 

Many applications change the shape of the cursor 
depending on what it’s currendy oven The standard 
movie controller never changes the cursor, but other 
movie controllers might want to. Unfortunately, many 
applications need to control the cursor themselves — 
when a movie controller changes the cursor, diese 
applications change it back immediately. 

A simple solution is for applications to change the 
cursor only when ids first placed over a movie. (To 
determine whether a point is over the movie, use 
PointinMovieQmti'oller) After that, let the movie 
controller control die cursor imtil it exits the area 
over the movie. To give the mo\ie controller the 
opportunity to change the cursor’s shape, you must call 
either MCIsPlayerEvent or iMCTdle Erequendy while 
the cursor is over the movie, even if the movie is 
stopped. The sample movie controller on this issue’s 
CD changes the cursor w’^hen it’s over the movie, 
providing an easy w^ay to debug such a scheme. 


A second solution is to stop the movie controller from 
displaying its help balloons — necessar)^ if you want to 
display your owti help for QuickTime movies. To do 
this, install an action filter on the movie controller. 
Ever}" action that occurs in the movie controller (play, 
step, update, key down, and so on) is passed through a 
single fdter function. Through this filter, an application 
can gain access to all activity that occurs in the movie 
controller. 

The MegaMovies application on this issue’s CD 
pro\ides a window^ that displays events that pass 
through the action filter. The action of interest is 
mcActiunShow^Balloon, Mdien this action is sent, 
QuickTime is about to put up a new" help balloon. One 
of the parameters passed to the action filter is a pointer 
to a Boolean. The filter can set this Boolean to false to 
tell the movie controller not to show" a balloon. The 
fidlowing code fragments show how to install a simple 
action filter to prevent the movie controller from 
displaying help balloons. 

pascal Boolean noBalloonsActionFliter 

(HovieControlIer mct short action, 
void *parains, long ref Con) 

{ 

if (action ~ mcActionShowflalloon) 

*(Boolean *)parains “ false; 
return false; 

} 


MCSetActionFiIterWithRefCon(mef 

& noB alloo n sActionFliter, 0); 


WINDOW ALIGNMENT 

A simple w^ay to improve a QuickTime movie’s 
playback performance is to ensure that the movie is at a 
good location on the screen. The exact definition of a 
“good location” varies, based on the screen depth and 
the processor, A lyi>ical good location is one w^here the 
first pixel of each scan line begins on a long-word 
boundary. This allow^s the decompressors to wTite data 
in the most efficient w^ay. On slower machines, proper 
placement can provide the necessary performance 
improvement to deliver smooth playback. 

Fortunately, applications don’t have to understand the 
details of how" to find a good location. QuickTime’s 
Image Compression Manager provides routines to 
position a window* at these locations. Wlien you create 
a window, you can use AlignWindow' to move it to a 
good location before making it visible. If a window" is to 
l)e moved. AlignScreenRect will niodily the chosen 
location to make it a gtxid location. WTien die user 
drags a w^indow, call DragMignedMindow instead of 
DragWindow to place the windtjw" in a good location. 
Examples of these calls are shown lielow". 


WindowPtr w; 
Movie m; 
Rect r; 


// Code to create a properly aligned window, 
w = GetNewCWindow(12S, nil, (WindowPtr)-1); 
m = getMovie(); 

GetMovie B ox(m, & r); 

AlignWindow(w, false, &r, nil); 
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// Code to drag a window with a movie in it and 
// keep the window aligned properly. 

GetMovie Box(m, & r); 

DragAlignedWindow(w, theEvent,where, nil, &r, nil); 

These alignment routines were added in QuickTime 
1.5, so make sure that QuickTime 1,5 or later is 
installed before you call them. 


MOVIE CONTROLLER EDITING 

The standard movie controller supports the editing 
commands Undo, Cut, Copy, Paste, and Clear, but this 
functionality is turned off by default. To turn it on, call 
MCEnableEditing as follows: 

MCEnableEditing{mc, true); 

You can then use movie controller routines to 
implement editing: 

Movie m = nil; 


switch {aditMenuSelection) { 


case menuUndo: 

case menuCut: 
case menuCopyi 
case menuPaste; 
case menuClearj 


if (m 1= nil) { 

Pu tMoVieOnS cr ap{ 
DisposeMovie{m); 
} 


MCUndo(me); 
break; 

m = MCCut(inc); 
break? 

m = MCCopy(mc}; 
break; 

MCPaste{nic, nil)? 
break? 

HCClear(inc) ? 
break; 


r 0); 


Now you have to enable and disable the various menu 
items. You could call MCGetControlIerlnfo, which 
returns a long w^ord of flags indicating, among other 
things, which Edit menu items should be enabled. 


With QuickTime L5, there’s an easier w^ay: call 
MCSetUpEditiMenu, and the movie eontroller will 
enable and disable the items in the Edit menu for you, 

MCSetUpEditMenu(me, theEvent.modifiers, 
editMenuHandle); 

This routine will even change the menu contents if 
appropriate. For example. Undo becomes Undo Paste 
if the last movie controller action was Pasie; after Undo 
Paste is chosen, it becomes Redo Paste, VVliat’s more, if 
the user holds dowm modifier keys when pulling down a 
menu, other coiiunands change as well. For example, 
holding dtmn the Option key changes Paste to Add and 
Clear to Trim. (See Figure 2.) 
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Figure 2. Standard and modified Edit menus 

MCSetUpEditMenu assumes the Edit menu is 
arranged in the standard way. If yours is nonstandard, 
you’ll need to use MCGetJVIenuString to obtain the 
appropriate text for each standard Edit command, and 
then enable and disable the menu items according to 
the infomration fi-om xMCGetControllerlnfo. 

JUST DO IT 

It’s so easy to add movie playback support that it’s often 
well w'onh the effort. As long as you keep these few 
simple things in mind, you shouldn’t have any 
problems, even with future versions of QuickTime. 


Thanks fo Jim Batson, Ken Doy[e, and John Wang for reviewing 
this column. * 
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Programming for Flexibility: 
The Open Scripting Architecture 


Users — and developers — waited a long time for the Macintosh 
Operating System to suppoi^ the ability to attach and run scripts as a 
way of customizing applications. The Open Scripting Architecture 
(OSA) thafs part of AppleSaipt finally provides the necessmy services. 
Now you can realize missive gains inflexibility by using embedded 
saipts and can pass sknilar gains along to the user by making your 
application OSA savvy. 



PAUL G. SMITH 


Thanks to Apple*s Open Scripiiiig Architecture (OSA), an application can now be as 
flexible as a set of Lego building blocks. Defining the program's high-level behavior 
using scripts instead of traditional prognim code makes possible an unprecedented 
amount of flexibility, a cause for celebration particularly among in-house developers 
and developers of custom software. Want to make a change in the way your software 
works? It's simple to modify the scripts that define the behavior of the objects 
involved. Want to make a customized solution, using the program's components as 
building blocks? Easy: just wTite some new scripts. Want to construct an OpenDoc 
part from your program? You're already partway there. 

Varying degrees of OSA support are open to your appheation. "Fhe OSA gives you 
the ability to do the following: 

• execute scripts previously created with the AppleScript Script 
Editor 

• store compiled scripts and other script values in your program and 
data files 

• directly compile and execute scripts 

• decompile existing scripts, for editing 

• use embedded scripts to automate your program's handling of 
Apple events 

• enable users to customize and extend your program's capabilities 
by attaching scripts to ol)jects in the application's domain 


PAUL G, SMITH (AppleLink SMITH.PG) is a 
developer ond consultani specializing in intelligent 
agent software, computer-bosed communicofions, 
and object-oriented progronnming techniques, 
currently in his eleventh year of developing for the 
Macintosh. He divides hfs time between the 
offices of Full Moon Software Inc. near Cupertino, 
Californio, and his native England, where he runs 


a smofi Europeon consultancy called commstdk 
hq and lives with his wife, Steph, and his cat, 
Mack. Steph leads a more glamorous life than 
Paul, having been a dancer in big productions in 
the London West End and now making glorious 
hats os o fashion milliner; Mock leads on easier 
life than Paul and takes a lot more naps.* 
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Further, the OSA makes it possible for all customizable applications to present a 
common set of scripting languages anti dialects for users to choose from. 

This article orients you to the OSA by outlining an OSA-sawy programming 
structure and then describing techniques you can use to import scripts from the 
Script Editor, run a script in your application, attach scripts to objects, compile and 
decompile scripts, route Apple events to scripts, and handle user-interface events. 

The programming structure and these techniques are demonstrated in the source 
code for the sample program SimpliFace on this issue’s CD. The AppleScript 
Software Development Toolkit, available from APDA, contains the essential tools for 
OSA development. 

STRUCTURING THE OSA-SAWY PROGRAM 

You need to do some preliminary' setup work in your application before you can take 
full advantage of the services offered by the OSA and make use of scripts. Depending 
on how your application is already strocrured, this can mean anj^irhing from a slight 
restructuring to a complete rewrite from die ground up. Fll describe the basic 
requiremenLs for an OSA-sawy program here and then show you the structure of 
SimpliFace so that you can see how one looks. 

THE BASIC REQUIREMENTS 

The first requirement for an OSA-sawy program is that it comply with the Apple 
event object model. As you probably know, this model sets out a standard way of 
stnicruring a program so that it can be controlled from other programs and so that 
ids scriptable using standard terminology familiar to the user. This model is solution 
oriented (that's the crucial part) because it concentrates on what users do with the 
application, not on bow they and the application do it. The articles ^^Lpple Event 
Objects and You” in dr^elop Issue 10 and Better Apple Event Coding Through 
Objects” in deiwlop Issue 12 provide useful infonnacion about the Apple event object 
model and how to support it in your application. The Apple Event Registry is the 
essential reference for standard Apple event classes and contmands. 

The second requirement (which isn't completely separable from the first) is that the 
application be fiiUy factored •— that is, that it separate the interface from the 
operations. In a factored program, the actions that result when users choose menu 
items, click buttons, and so on, generate a sequence ol Apple events. \‘\Tien a user- 
initiated action is dispatched as an xAppIe event, or when an external program or script 
sends an Apple event, the program resolves which object the Apple event relates to. It 
then passes the Apple event to the appropriate handler for that object; this program 
code is responsible for the object’s behavior. 

\\dien your application complies with the Apple ev^ent object model and is frilly 
factored, and w'hen it publishes its scripting terminology, it’s possible to make it 
attachable — that is, to make it handle and store the data involved in the process of 
embedding or attaching a script. (I say “embedding a script” when I mean building 
one in at the program development stage, w^hereas I refer to “attaching a script” w^hen 
I mean it’s added or modified by the user.) And once your program enables scripts to 
be attached to objects such as windows, documents, and the application object itself, 
these scripts can customize the program’s handling of object-model Apple events. 

Scripts attached to program objects can affect the behavior of the program and its 
objects in two cases. In the first case, scripts attached to objects can modify the 
beharior of those objects when Apple events are resolved and handled. In the second 
case, scripts attached to user-interface objects like menus and buttons can define the 
sequence of Apple events that result from user-initiated actions. Both of these 
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mechamsEiis may have a place in your application. Fortunately, your application's 
structure doesn't have to chajige much to allow scripts to customize behavior. 

An attachable program can give a compiled script first crack at handling an incoming 
Apple event instead of passing the event first to the handler (the program code tliat 
defines the object’s behavior). If the script handles the Apple event, the program code 
doesn’t get called; if the script continues the Apple event (that is, passes the message 
to the script’s parent object) or if it doesn’t handle it, the program code gets called as 
usual, as illustrated in Figure 1. If necessary, the script can modify or add to the 
original parameters for the Apple event before passing it on to the program code. 

For more On handling Apple events, see Jhe description oF command hondlers 

on poge 241 of tFis AppleScript Language Guide.* 


Incoming Apple event 


Program code 
that defines 
behavior 


In o program that's not attachable 




Progrom code 
that defines 
behavior 


In an attachable program 


Figure 1. Routing an Apple event 


Thus, attaching scripts to objects can make the operation of your program a great 
deal more flexible. But you can go even further: instead of generating Apple events by 
making long-winded calls to the Apple Event Manager in response to user-initiated 
actions, you can attach scripts to user-interface objects. Selection of one of these 
objects then results in a script being called; the result of executing the script is that 
the appropriate Apple events are sent, as illustrated in Figure 2. In the first case, the 
primajty^ reason tiie program makes the Apple event calls is so that the action is 
recordable; in the second case, the script makes the Apple event calls anyway, so that 
no extra work is required to make the action recordable, and thus the recordability 
comes for free. The overhead involved in diis is minimal (and it may even reduce die 
bulk of program code); the increased flexibility is massive. It’s not even necessary to 
make these embedded scripts user changeable — that’s entirely up to you. 

A SAMPLE PROGRAM: SIMPLIFACE 

The sample program SimpliFace on this issue’s CD demonstrates the principles just 
outlined. SimpliFace is a basic scriptable and attachable user-interface builder written 
in MPW C++. SimpliFace constructs scripted windows that can contain text labels 
(diough not editable text) and buttons. It demonstrates many of the features of the 
OS A APIs, uses a lightweight C++ framework for Apple event object model 
compliance, suggests a novel approach to a fully factored application, and allows 
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Figure 2, Generating Apple events 


scripts to be attached to all application objects. SimpliFace has little preprogramoied 
behavior; virtually everything is defined through scripts supplied by the user, 

SimpliFace is built around a rough-and-ready C++ framework, inspired by the one 
used in the Apple Shared Library Manager’s sample applications* I like to use 
lightweight C++ classes that don’t depend on one another too much (thus aiding their 
reuse), so the program structure isn’t as tightly integrated as that of, say, a MacApp 
program. In the spirit of other Apple sample applications, most ol the error handling 
has been left for later. 

Figure 3 illustrates the object containment hierarchy for SimpliFace at run time. 
There is one application object, which can contain zero or more window objects. 

Each window object can contain button objects and/or text label objects. 



Figure 3. SimpliFace^s object containment hierarchy 


Figure 4 shows the SimpliFace class hierarchy. All application-domain scriptable 
objects derive from a TScriptableObject class (see the source fi.le ScriptableObjects.h) 
that has an attached script and is able to assist wdth object resolution and Apple event 
handling. A TObjiModelToken class (see ObjModelTokens.h) is defined to manage 
token resolution and Apple event dispatching; the interaction of these is tnanaged 
from a set of static functions in the file ObjModelEvents.cp. 
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Figure 4, SimpllFoce's class hierarchy 

The application’s behavior is defined in the files Applicationxp and SimpliFace.cp 
(the latter contains the main program ftmetjon). Outside the program’s object 
containment hierarchy, a separate script administrator class, TScriptAdministrator, is 
defined. This class is responsible for fetching the script attached to objects and 
preparing it for execution, and serves to encapsulate the script-hand ling code. Tfs 
implemented in the file ScriptabieObjects.cp, 

The window, button, and text label objects are created by sending SimpliFace 
appropriate Apple events. VVlien it receives an Apple event, SimpliFace resolves the 
object that the event is aimed at (the direct parameter of the event specifies the target 
object). SimpliFace then dispatches the Apple event (unless ifs an Open Application, 
Get Data, or Set Data event) to the script of the target object. The work for this is 
handled in the file Ob jMod el Events, cp. We’ll look in greater detail at how SimpliFace 
handles an incoming Apple event in the section ""Routing Apple Events to Scripts.” 

Two sample scripts written in the AppleScript language are supplied to demonstrate 
SimpliFace; you can run these using the Script Editor. One is the startup script that’s 
run whenever SimpliFace is launched, and the other (culled Te.st Simple Wndow) 
creates a window that contains two buttons and a text label. Here’s the latter script: 

make new window 

with properties {name;^Tests'", bounds:{60, 60, 350, 300]■> 
set the script of window “Tests” to winScript 
open window "Testa" 

make new button 

with properties {name: “Quitkind:standard, bounds: {10, 50, 80, 70}} -■ 
at end of window "Tests" 
make new button 

with properties {name:"'Hello", kind:standard, bounds:{10, 10, 80, 30}} 
at end of window "Tests" 
make new text label 

with properties {name:"Data entry", contents:"I'm a text labeli", ^ 
bounds:{90, BO, 280, 130}} 
at end of window "Tests" 

Open the SimpliFace Dictionary, using the Script Editor, to see more details of the 
scripting interface. 


































DEBUGGING SIMPLIFACE 

To help debug the Apple event handlers in SimpliFace, I Implemented a simple debug 
transcript tool* A small amount of code (borrowed from AAocApp) is used to intercept 
the MPW <stdio> library. The informotion thus captured is packaged and sent via a 
private Apple event to the Debug Transcript program^ which you'll find along with the 
rest of SimpliFace on the CD. 

The debugging mechanism Is managed in the SimpliFace module DebugTrace. If you 
open the Debug Transcript program before you run SimpliFace^ o lot of information 
about Apple events received and processed will op pear in the transcript window. 
Apple events are decoded in the Apple event prehandler using the AEPrint routine^ 
part of Jens Alfke's AEGizmos llbrory. You can add to the information displayed 
simply by adding extra printf statements to the program code. 


SimpliFace doesn’t store window properties or object scripts on disk, so every time 
you launch it you need to set up the application script, and you must recreate all 
windows and window c>bjects. This is facilitated by the automatic loading and 
execution of the startup script (called SimpliFace Startup) whenever SimpliFace is 
launched* 'lb prevent this script from running, hold down the Control and Command 
keys while SimpliFace starts up. The mechanism used to run this script is described 
under “Running Scripts” later in this article, 

TECHNIQUES FOR OSA-SAWY PROGRAMS 

Now^ that you have a general idea of how to structure an OSA-sawy program, we’ll 
consider the specific teclmiques your program can use to take advantage of the OSA’s 
services and enjoy the flexibility offered by using scripts* 'Fhis section describes how 
to import scripts from the Script Editor, run scripts from within the application, 
attach scripts to objects, compile and decompile scripts, route Apple events to scripts, 
and handle user-interface objects. You won’t necessarily need to implement all of 
these techniques in your program, but you should be aware of them so diac you can 
decide how you want tc} implement scripting. 

IMPORTING SCRIPTS FROM THE SCRIPT EDITOR 

Unless you have a specialized requirement and want to wTite your own script editor, 
you’ll get the best mileage by creating and compiling scripts with Apple’s Script 
Editor and then importing these scripts into your application* You have some choices 
about how to approach importing scripts into your application: 

• You can keep the *scripts in Script Editor files and load them only 
wTien needed* This is the approach SimpliFace takes with its 
startup script: it looks in the same folder as the application for the 
file called SimpliFace Startup and loads and executes the script 
from that file* 

• Extending this approach, your program can maintain a folder of 
script files and look there for named files. For the user, adding a 
new script file is as easy as dragging it to die folder in the Finder. 

• ^Alternatively, your program can offer an import function that 
allows the user to select a script file from which a compiled script 
is to be imported. Your program can then store the compiled script 
ol>ject in any way it wishes, using its own data storage mechanisms* 
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Before we examine the technique you should use to import scripts, we need to quickly 
review how the Script Editor and the OSA store scripts. AppleScript can compile 
scripts in two forms* as contexts, which can contain handlers (for Apple events and 
user-defined subroutines) and properties, and as ordinar}?^ compiled scripts, which can 
only be executed. The Script Editor alw^ays compiles and saves scripts as script 
contexts. To the OSA, compiled scripts are values and can be stored in variables and 
manipulated just like numbers, text, lists, or records. WTien a program passes a script 
value to the OSA, or when the OSA passes a script value to a program, it^s referred to 
through a special magic cookie called an OSAID. OSAIDs are 32-bit-long integers, 
and the OSA uses an internal mechanism to map these onto the data they refer to. 

The OSA provides a pair of routines that you can use to convert OS.AQDs to and from 
data handles you can save. OS AS tore converts an OSAID into an AEDesc (Apple 
event descriptor), of wdiich the data handle portion can be saved. OSxALoad does the 
opposite, unpacking the contents of the data handle portion of an AEDesc (previously 
saved using OSASrore) to create a new OSMD. A compiled script context that^s been 
saved using the OSAStore command is contained in resource number 128 of type 
'sept' (kOSAScriptResourceType, the same constant as typeOSAGenericStcjrage), one 
of the four resources of a Script Editor compiled script file. 

The AEDesc is the bcisic Apple event datci structure, described in tnside 

Macintosh: inferopplication Communication, Chapter 3, and the earlier Inside 

Macintosh Volume Vf Chapter 6.* 

SimpliFace’s LoadScriptlAomFile routine, shown in Listing 1, imports a compiled 
script from a Script Editor file; you can use it as a model regardless of w hich of the 
three approaches outlined above you choose to take, llie key tasks undertaken by this 
routine (apart from locating and opening the resource fork of the script file) are 
loading the resource handle, putting a reference to it into an ^AEDesc of t)pe sept' 
(typeOSAGenericStorage), and calling OSiALoad to generate an OSAID that refers 
to the compiled script. 


Listing 1, TScnplAdminisfraroniLoadScriptFromFile 

OSAError TScriptAdministratorsiLoadScriptFromFile[FSSpec *fileSpeC| 

OSAID ^theScriptlD) 

{ 

short fileRef = FSpOpenResFile{ fileSpec, fsHdPerni)? 

OSAError err = ResError(); 

if (err == noErr) { 

Handle h = GetlResourcejkOSAScriptResourceType, 128); 
if (h 1= nil) { 

AEDesc scriptData; 

sc ript D at a.de s c ript orType = typeOS AGe ne ric S t o ra ge; 
scriptData.dataHandle = h; 

err - OSALoad(gScriptingComponent, sscriptDatai 
kOSAModeNull, theScriptID); 

ReleaseResource(scriptData.dataHandle); 

} 

CloseResFile(fileHef); 

} 

return err; 
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RUNNING SCRIPTS 

Now th;at youVc loiiclcd the script, it can be executed. So how do you run a script in 
your application? Tfs easy — all you do is pass the compiled script (which can be a 
script context or a simple compiled script) to the f)SA routine OSAExecute. To show 
how iris done, here’s some code from SimpliFace that executes die startup script: 

FSSpec theFileSpec; 

OSAID startupScript = kOSANullScript? 

// ... Set up theFileSpec here.,.. 

err = LoadScriptFrDinFile{ stheFileSpec, sstartupScript); 
if (err == noErr startupScript i= kOSANullScript) { 

OSAID resultID = kOSANullScript? 

err = OSAExecute (gScriptingComponerit, startupScript^ 

kOSANullScripti kOSAHodeWull, SresultlD); 

// ... More code goes here,* * * 

> 

The first parameter to the OS.AExecute routine and all other OSA routines is the 
scripting component instance. To make any OSA calls, you need to have opened a 
comiectitm to a scripting component (in this case, AppleScript) by means of the 
OpenDefaultCornponent call. This returns a component instance that you can save 
(in this case, as gScriptingComponent) and pass to future OSA calls. 

The second and third parameters to OSAExecute are both OSAIDs referring to 
compiled scripts. The second parameter refers to the script to he executed and the 
third parameter refers to the script context in wEich global variables will be bound 
(if the script to be executed is a normal compiled script). Script contexts in the 
AppleScript OSA component are equivalent to script objects in the AppleScript 
language, W^Tienever a script object is compiled tiiat contain.s commands in the body 
(not inside a handler), these commands are collected into a default run handler (the 
handler that’s executed when the script object is sent the run message). The Script 
Editor uses tills same method to execute scripts. The run handler executes using the 
context to access and store properties and global variables. 

In the above fragment, we supply kOSANulIScript for the third parameter because 
the script weVe loaded from the Script Editor file is a script context. If a script 
context with a run handler is given as the second parameter to OSAExecute, the run 
handler is extracted from the context and used as the compiled script. In this case, the 
third parameter passed to OSAExecute is ignored. 

The above code from SimpLLFace executes a predefined compiled script that sets up 
the initial state of tlie program. You can use the same technique to attach scripts 
directly to menu functions or to buttons in dialog !>oxes and data entry forms, but I 
don’t recommend that because you can gain mure flexibility by generating Apple 
events from user actions and then letting stTipts handle the events. You can also use 
this technique to extend your application so that scripts are mggered wEen 
interesting events occur. For instance, if you were wxiting a storage management 
utility you could let the user declare timers that triggered scripts at predefined 
intervals or at specified times of the day or w^eek to perform backups and disk 
reorganizations. 

AHACHING SCRIPTS TO OBJECTS 

Attaching a script to an application-domain object can be a simple matter of 
extending the definition of the object to include a script property’^. The Apple Event 
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Registry" defines a class, property, and Apple event data type for script properties. The 
constants for all these have the same value: ’sept' (typeOSAGenericStorage). 

SimpUFace demonstrates how a script property can be attached to an object. As noted 
earlier, all application-domain objects in SimpliFace that have an object-model 
counterpart are derived from the class TScriptableObject. The definition of this class 
includes a field of type OSAID called fAttachedScript, referring to the objects 
attached script. Listing 2 shows the source code of the SetProperty function from the 
class TScriptableObjecL 


Listing 2* TScnptableObject::SetProperty 


OSErr TScriptableOb j ecti:SetProperty(DescType propertyID, 

const AEDesc *theData) 


{ 

OSAError err = errAEEventNotHandled; 


// Used switch statement instead of if statement to allow for 
// future expansion, 
switch (propertylD) { 
case pSoript: 

OSAID theValuelD = kOSANullScript; 
if {theData->d6ScriptorType == typeChar 

I I theData->descriptorType == typelntlText) 
err = OSACompile(gScriptingComponent, theData, 

kOSAModeC ompi lei ntoC o nt e xt, £i theV a 1 u e ID); 
else // If it's not text, we assume the script is compiled, 
err = OSALoad[gScriptingComponent, theData, 
kOSAHodeNull, &theValuelD); 
if [err — noErr) { 

if (fAttachedScript I- kOSANu11Script) 

OSADispose{fAttachedScript); 
fAttachedScript = theValuelD; 

} 

break; 

} 

return (OSErr)err; 


You or the user can write an AppleScript script that sets the script property of an 
object. Kerens an example that sets the script property of a window object: 

tell application "SimpliFace" 
script inyWindowScript 
on close 

global numTimesClosed 

set numTimesClosed to numTimesClosed + 1 
continue close 
end close 
end script 

set the script of window "MyWindow" to myWindowScript 
end tell 
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If your application is constructed so that parts of the runtime behavior are defined 
using attached scripts, it becomes feasible to write other scripts that update the 
application to its latest version. These scripts could even update applications across a 
netw^ork. WTiat a boon this would be to MIS departments! 

COMPILING AND EXECUTING SCRIPTS 

In some circumstances, your program will need to compile a script itself instead of 
impcjrting a compiled script from the Script Editor. For instance, the Do Script 
Apple event lets the scripter supply the script source code as the event’s direct 
parameter. To handle this Apple event, your program needs to compile the source 
code before it c-an be executed- You might also want the user to be able to set the 
script property of an object by supplying the source code instead of a compiled script. 

I'he OSA provides a routine called OSACompile that compiles script source code 
and returns an OSAID. The SimpliFace function TScriptabIeObject::SetPropert>", 
shown in Listing 2, uses OSACompile. 

SimpliFace uses a different routine, OSACompileExecute, to implement the Do Script 
Apple event. This is a convenience routine that compiles some script source code and 
immediately executes it. Listing 3 shows DoScript, the SimpliFace function that 
handles the Do Script Apple event. In this function, the AEDesc scriptDesc contains 
the script to he executed. The data type is checked to see if it contains source codei if 
so, the script is compiled and executed using OSACompileExecute. If a script value 
result is returned by the OSA, it’s coerced to an AEDesc and returned in resultDesc. 


Listing 3* T5criptAdministrafor::DoScnpr 


OSAError TScriptAdministrator;;DoScript(AEDesc *scriptDesc, 

AEDesc ^resultDesc) 


{ 

OSAError err = errMEventNotRandled? 


if [scriptDesc nil && (scriptDesc->descriptorType = typeChar 
II scriptDesc->descriptorType == typelntlText)) { 
OSAID resultID = kOSAKullScript; 

err “ OSACompileExecute[gScriptingComponent, scriptDesc, 

kOSANullScript, kOSAModeAlwaysInteract, SresultlD)? 
if (err 1= noErr) 

DmripOSAerrorInfo(gSGriptingComponent, err); 
else if (resultID 1= kOSAKullScript) 

err = OSACoerceToDesc(gScriptingComponent, resultID, 
typeWiIdC ar d, kOSAMo deKu11, re su1tDes c); 
OSADispDse{gScriptingComponent, resultID); 

> 

return err; 

> 


Eagle-eyed students of the Apple Event Registr}^ will notice that the DoScript 
function doesn’t implement the other standard form of the Do Script Apple event, 
which allow^s the script to be specified by reference to a script file on disk. As 
discussed earlier in the section “Importing Scripts from the Script Editor/’ the source 
code for SimpliFace includes a mechanism to read a script from a script file, so Til 
leave it to you to modify TScriptAdministraton:DoScript. 


PROGRAMMING FOR FLEXIBILITY: THE OPEN SCRIPTING ARCHITECTURE 


35 






DECOMPILING SCRIPTS 

The counterpart of the Set Data Apple event is the Get Data Apple event* ^\n 
attachable application should allow scripts to get^ as w^ell as set, the script property of 
objects. By^ default, the script property should be returned as a compiled script, but 
the definition of the Get Data Apple event permits the caller to request a property as 
a different data type. If this data type is text, and if the script property of an object is 
being requested, your program will need to decompile the script* 

The function OSAGetSource is used to extract die source code from a compiled 
script. SimpliFace demonstrates the use of OSAGetSource in the GetPropeHy^ 
function from die class TScriptableObject (see Listing 4)* The SimpliFace Get Data 
handler extracts the desired data type from the Apple event and passes it to the 
GetProperty function in the parameter w^antType; if the caller doesn’t specify a data 
ty^e, typeWiidCard is used to signify the default type for the property. Tf the object 
has an attached script, GetPrf)perty checks to see what data type is requested by the 
caller* If the data type is text, the script is decompiled and the source code is returned. 
Otherwise, the compiled script is returned as the result using the OSAStore function 
(die converse of OSAI..oad, discussed earlier)* 


Listing 4, TScriptableObjecf::Ge^Property 


OSErr TScriptableObject:sGetProperty(DescType propertylD, 

DescType wantType, AEDesc *result) 


OSErr err = errAEEventNotHandled; 


switch (propertylD) // Used to allow for future expansion 

{ 

case pScript: 

if (fAttachedScript J= kOSAHullScript) ( 

printf{”!;GetProperty{); get script as type '1.4s'Xn", 
f char*)fiwantType); 

if (wantType == typeChar || wantType == typelntlText) { 

// If caller wants text, we need to decompile the script, 
err = (OSErr)OSAGetSource(gScriptingComponent, 

fAttachedScript, wantType, result)? 

} 

else { 

if (wantType == typeWildcard) 

wantType = typeOSAGenericStorage; 
err = (OSErr)OSAStore(gScriptingComponent, fAttachedScript, 

wan tType, kOSAMode Nul1, result); 

} 

} 

break; 

} 

return err; 


ROUTING APPLE EVENTS TO SCRIPTS 

As noted earlier in this article, the way to customize your application’s handling of an 
object-model Apple event is to pass the event to an attached script first, passing it to 
the program’s normal handler for that event only if the script fails to handle or 
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continues the event. Note that this can be done only if the attached script was 
compiled as a script context; simple compiled scripts can't be used this way. The OSA 
provides tu^o functions for passing Apple event handling to script contexts: 

OSAExecuteEvent remms the result of executing the script as an OSAID that you 
must coerce back to an AEDesc to supply to the reply event, and OSADoEvent 
automatically puts the result into the reply event, 

OSADoEvertf had a problem m version 1.0 of AppleScripl: it never disposed of 
the temporary OSAID it used to hold the result of executing the script. This could cause 
the AppleScript 1.0 component to foil. The recommended workaround was to use 
OSAExecuteEvent. This problem wos fixed in AppleScript 1.1." 

The AppleScript language permits a message to be "'continued” — that is, passed to 
the parent of the script object that's currently handling the message. The AppleScript 
Continue statement is similar to the Pass statement in HyperTalk, The OSA allows 
your program to get in on the act when a message is continued, by specifying a 
resume/dispatch procedure (so called because it lets your program resume handling 
of a continued event or dispatch an event that isn't handled in the script). To do this, 
you use the OSASetResumeDispatchProc call. The resume/dispatch procedure takes 
the same parameters as an Apple event handler and might be your application's 
default handler for the Apple event in question. It will be called by the OSA during a 
call CO OSAExecuteEvent or OSADoEvent if the script continues the Apple event. 

The OSA also allows you to specify^ another kind of resume/dispatch handling: if 
instead of specifying an actual Apple event handler for the resume/dispatch procedure 
you pass the special constant kOSAUseStandardDispatch or kOSADontUsePhac, and 
if the script continues the handling of an Apple event, it will he dispatched direedy to 
the default Apple event handler for that event, ignoring any special prehandling. To 
make full use of this facility, you need to implement an xApple event prehandler 
procedure in your program as well. 

The prehandler gets first crack at any incoming Apple event; it’s called for all xApple 
events that are dispatched to the application, except those that have been 
redispatched by the OSA (assuming you set up resume/dispatch handling as just 
described). A prehandler procedure is installed by calling the Apple Event Manager 
function xAEInstallSpeciaLHandler. 

To illustrate how Apple events are routed to scripts, let's look in detail at how 
SimpliFace handles an incoming xApple event. 

L The Apple Event Manager routine AEProcessAppleEvent passes 
the event to the program’s Apple e\^ent prehandler procedure. 

2. The prehandler procedure tries to resolve the application-domain 
object that should handle the Apple event, by resolving the event's 
direct parameter 

3. If an application-domain object is successfully resolved and if it has 
a script attached, the resume/dispatch mechanism is set up and the 
Apple event is passed to the script by a call to OSADoEvent, If the 
script handles the Apple event successfully, weVe done with it. 

4. If the script doesn't handle the Apple event, the OSA returns the 
error err/\£EventNotI land led, which the prehandler returns as its 
result. The Apple Event Manager then redispatches the Apple 
event to the appropriate installed handler. 

5. If the script continues the Apple event, it’s redispatched by the 
OSA directly to the installed handler for that Apple event. 
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6. If there is no script to handle the event (maybe the application- 
domain object doesn’t have an attached script) or the attached 
script handles but continues the Apple event, the handler yon 
previously installed for die Apple event receives the event and tries 
to resolve the application-domain object that should handle it 

7. If an application-domain object is successfully resDlved, ids asked 
to handle the Apple event, implementing the object’s standard 
beha\aot 

The prehandier routine from SimpliFace is shcmm in Listing 5. The routine starts by 
extracting the Apple event class and ID frtim the event record. It then checks to see if 
the attached-script behavior should be ignored: SimpliFace doesn’t pass the Open 
Application, Get Data, and Set Data Apple events to attached scripts. The routine 
then tries to resolve the direct object of the Apple event, creating a token object. If no 
token is resolved, a token that refers to the application object is created. A global 
script administrator object is dien asked to locate and return the attached script; 
unless there was no attached script, the Apple event is passed to die script by calling 
the SimpliFace routine ExecuteEventInContext, which in uirn calls OS^ADoEvent. If 
the script fails to handle the Apple event, or if an error occurs, the error is returned 
via the Apple Event Manager. 

HANDLING USER-INTERFACE EVENTS 

User-interface events, such as mouse clicks, keystrokes, and menu selections, are 
handled in a special way in SimpliFace. This allows SimpliFace to delegate the 
l)chavior of these user-in ter face objects to dieir attached scripts. User-initiated mouse 
and keyboard actions are intercepted by a routine in Simplil'ace.cp called 
TSimpliFace::HandleFvent. This routine, in conjunction with a group of support 
routines, packages and dispatches the user-initiated event as a system event. This 
special kind of Apple event is dispatched to the script of the object the user clicked in, 
if there is one, or the current window if not. If diere’s a mouse click in a text field or 
button, the script for the field or button (if there is one) gets the event. 

If any runtime error occurs in a script while an event is being handled, or if the 
message is continued out of the last handler that caught it, or if an event isn’t handled 
at ali, the normal behavior for that event takes place in the program code. For 
instance, when a SimpliFace window is dosed (either by a script’s sending a Close 
event or by the user’s clicking in the window ’s dose box), a Close event is dispatched 
to the window’s script (if it has one). If this script handles the event and returns 
without error, the Close event goes no further and the window stays open. If the 
script lails to handle the event or continues the Close event, the window^ is dosed by 
the default Apple event handler in the C++ program code. 

FURTHER OSA SUPPORT 

Now that you have a grasp ol the basic requirements of an OSA-saw^^ program and 
know^ the techniques to import scripts from the Script Editor, run those scripts, 
attach scripts to objects, compile and decompile scripts, route Apple events to scripts, 
and handle user-in ter face events, you may w^ant to go even hircher with your support 
of the OSA. There are two issues in particular that you may w^ant to address: how^ to 
handle global variables so that variables can be shared between scripts, and how to 
allow scripts to share libraries of subroutine handlers so that the application object’s 
attached script behaves something like HyperCard’s stack script 

IVe completed another version of SimpliFace that implements these features, and it 
may be the subject oi a future article in develop — if you clamor loudly enough for it. 
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Listing 5. StdAEvtPreHandler 


static pascal OSErr StdAEvtPreHandler(AppleEvent *theEvent, AppleEvent *theReply, long theHefCon) 


{ 


OSAError 

AEEventClass 

AEEventID 

DescType 

Size 

AEDesc 

OSAID 

ofa j Mode1Toke nPt r 
Boolean 


err = errAEEventNotHandled; 

theEvtClass ; 

theEvtID? 

theType; 

theSize; 

direc tPar am, t heTokenDes c ; 
theScriptID = kOSMullScript; 
theToken = nil; 
madeAppToken = false; 


theTokenDesc.descriptorType = typeWull; 
theTokenDesc.dataHandle = nil; 

// Extract the class and ID of the event from the Apple event, 

AEGetAttributePtr(theEvent, keyEventClassAttr, typeType, &theType, (Ptr) stheEvtClass, 
sizeof(theEvtClass), &theSize); 

AEGetAttribatePtr{theEvent, keyEventIDAttr, typeType, stheType, (Ptr) &theEvtID, 
sizeof(theEvtlD), & theSize); 

if ({theEvtClass == kCoreEventClass && theEvtlD i= kAEOpenApplication) 

I I {theEvtClass == kAECoreSuite && theEvtlD J= kAESetData && theEvtlD 1= kAEGetData) 

I I (theEvtClass == kSignature theEvtlD == kAESystemEvent) 

II (theEvtClass == kASAppleScriptSuite S& theEvtlD == kASSubroutineEvent)) { 

// Above test skips the events we don't want to be scriptable. 

err = AEGetParamDesc(theEvent, keyDirectOfaject, typeWildCard, fidirectParam); 
if (err == noErr) { 

err - AEResolve(&directParainr kAEIDoMinimum, stheTokenDesc); 

AEDisposeDesc(&directParamJ; 
if (err == noErr) 

theToken = ObjHodelTokenFroniDesc (fitheTokenDesc); 

} 

if (err i= noErr ]| theToken = nil) { 

err - MakeAppToken{(TObjModelToken**)StheToken); 
madeAppToken = (err noErr); 

} 

if (theToken 1= nil) 

theScriptID = gScriptAdministrator->GetAttachedScript(theToken->GetTokenObj()); 
if (theScriptID 1= kOSAHullScript) // Pass to script. 

err = ExecuteEventlnContext(theEvent, theReply, theRefCon, theScriptID, 
kOSAUseStandardDispatch, kOSADontUsePhac); 

else 

err = errAEEventNotHandled; 
if (theToken 1= nil) 

gScriptAdininistrator->ReleaseAttachedScript(theToken->GetTokenObj()); 

AEDispQseToken(stheTokenDesc); 

if (madeAppToken == true) // Will be executed only 

delete theToken; // if token was made locally* 

} 

return (OSErr)err; 
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Meanwhilt!, Fve left as an exercise for you a couple of other enhancements to 
SimpltFace: implementing editable text fields and making all window and button 
kinds and object properties work Roll up your sleeves and have a go at iu 
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Thanks to our technical reviewers Jens Atfke, 
Warren Harris, Ron Karr, and Jeroen Schalk.* 


9 Ways to Improve Your Mind In Your Spare Time 


DEVELOPER 


% 


LiNIVERSrrY 


Self-Paced Courses from Apple Developer University bring you a full range of technical 
training in your own home, at your own pace. 

• Macintosh Programming Fundamentals 

• Intermediate Macintosh Application Programming 

• Programmer’s Introduction to RISC and PowerPC 

• PowerTalk Templates 

• Object-Oriented Fundamentals 

• AppleTalk for Programmers 

• Apple Events/AppleScript Programming Tutorial 

• Programming with MPW 

• QuickTime Programming Tutorial 

To order the self-paced classes, contact APDA at 1-800-282-2732; for Developer 
University class schedules contact the Registrar at (408) 974-4897. 
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PETE ("LUKE") ALEXANDER 


GRAPHICAL 

TRUFFLES 

The Debugging 
Version of 
QuickDraw GX 


By now, majiy of you have instaJIed une of the beta 
versions of QuickDraw GX onto your Macintosh — 
and possibly by tlie time you read this, QuickDraw^ GX 
Software Developer’s Kit version 1.0 will be available 
from APDA. Maybe you’ve played with the v^arious 
sample applications and are now^ ready to work on your 
first QuickDraw GX application. Perhaps youVe even 
read my article in develop Issue 15, “Getting Started 
Wth QuickDraw GX.” In this column, Fll talk about 
something I referred to briefly in that article: the tw^o 
versions of QuickDraw^ GX’s combined graphics and 
layout portions, and how to take advantage of the 
debugging version during the development of your 
QuickDraw GX-based application. Along the w^ay 111 
update you on a few^ changes since I WTOte the article. 

THE EXTENSIONS OF QUICKDRAW GX 

The QuickDraw' GX system extension comes in two 
flavors^ a nondebugging and a debugging version. 
WTen you run the QuickDraw GX installer script, the 
nondebugging version is installed, including the 
complete QuickDraw GX system. The nondebugging 
version is lean and mean, so it’s significantly faster than 
the debugging version; it performs quite a bit less error 
checking than the debugging version. 

The debugging version of the extension protides 
extensive error checking and other debugging 
amenities. When developing a QuickDraw GX 
application, you should use tliis version to shake out 


the bugs. 'The debugging extension is in the DEBUG 
In it folder and is named “GXGraphics (debug)” in 
version LG {it used to be named aSecretGraphics.debiig); 
just drag it into your System Folder and reboot. As 
your system starts up you’ll see the debugging 
extension’s icon displayed before the QuickDraw GX 
icon. 

An explanation of w^hat’s really going on here may help 
clarify things (and it has changed): There are actually 
three extensions within foe QuickDraw^ GX extension 
— one for graphics and layout, one for printing, and 
one. for foe Finder printing extension. The QuickDraw 
CtX extension knows, if “CtXCiraphics (debug)” has 
already loaded, to use that extension instead of the 
nondebugging version of foe graphics and layout 
extension. {Note that since foe debugging extension 
must load before foe nondebugging version, you should 
not change foe debugging extension’s name.) 

THE ADVANTAGES OF THE DEBUGGING VERSION 
DURING DEVELOPMENT 

Let’s look at some differences betw^een foe two 
extensions, and specifically how to take advantage of 
foe debugging version during foe development of your 
QuickDraw GX application. 

Notices, warnings, and errors. With foe debugging 
version of foe extension, you can get three types of 
information about drawing problems: notices, 
w^amings, and errors. For a complete list of these, look 
at the graphics errors.h interface file. The many 
notices, warnings, and errors defined between #ifdef 
debugging and #endif in that file are available only 
with the debugging version. You’ll need to #define 
debugging in yoiu- application to take advantage of 
foem. (Make sure debugging is not defined when you 
build your final version.) 

With foe nondebugging version, notices aren’t 
available at all, and foe list of errors and warnings you 
need to respond to in your application consists only of 
those relatively few^ that lie outside #ifdef debugging 
and #endif in the graphics errors.h file. Your 
application must be set up to handle these errors and 


PETE ULUKE'^ ALEXANDER hos been providing developer 
support br QuickDraw GX ever since It was woy up m the air. 
He's happy tfs mokmg Its final opproach, and he's hoping If lands 
smack dab m the middle ol your softwore. As o glider plbt, Luke 
knows how Importont control is — ond with QuickOrow GX, you'll 
be able to moneuver your software info spaces you never thought 
possible. Since QuickDraw GX con help you do lots of great 
graphics stunts that you used to have to osk him about, Luke is 
about to SOOT oF into the wild blue yonder and do some stunts of 


his own. Soon he'll be ready br the prefligbt check that will launch 
his sabbatical faster than QuickDraw GX handles two-byte text. 

For many weeks he'll be thinking about nothing but white sand 
beaches, white puffy clouds, and white-copped mountoins. Hell 
lie on his bock and wotch the sway of the trees until they stop 
reminding him of the swashes of L's. So If you see him somewhere 
in Montano, Utah, Nevada, Collfornlo, or Idaho, be sure to say 
hello ’— but try not to use any words thot have a G and on X in 
them.* 
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warnings, which in general indicate diat the 
QuickDraw GX system could not honor your 
application's request. For example: 

shape_is_nil 

siz e_o f_pa t h_exc ee d s_imp1emen t ation_limit 
picture_in dex__ou t_o f _r an ge 

The debugging version checks for errors that you*re 
likely to run into while developing your application, 
such as passing a negative pen size to GXSetShapePen 
or a curve to GXGetGlyphMetrics. The nondebugging 
version doesn^t check for these types of eirfjrsj it 
assumes youVe already shaken them out of the code. 

Validation routines. The GXSetValidation and 
GXValidateShape routines are available only in the 
debugging version. These routines allow your 
application to tell whether it's passing valid parameters 
into a QuickDraw GX function, to validate the 
contents of all QuickDraw GX objects (such as a shape, 
style, and ink) before their use, and to validate the 
QuickDraw GX memory your application is using. 

Speed optimizations. The nondebugging version has 
optimizations for speed built in — not only fewer error 
checks but also inline functions. The debugging version 
doesn't optimize for speed. This shouldn't have any 
impact on your application development except that 
there's not a one-to-one correspondence between stack 
crawls using the debugging and nondebugging 
versions. A performance analysis of your QuickDraw^ 
GX application should only be done without the 
“GXGraphics (debug)” file in your Extensions folder. 

GraphicsBug. The GraphicsBug debugging tool 
allows you to explore the contents of any QuickDraw 
GX object to make sure it contains the correct 
information. Another change from before is that 
GraphicsBug is available in both the debugging and 
nondebugging versions. This ability to spy on an 
object’s contents is important to your application 
development because otherwise you could only access 
information in objects by making API calls, which 
%voijld be very tedious during debugging. 

'Fhere's a slight advantage when using GraphicsBug 
w^ith the debugging version: heaps are listed by name 
rather than by hex address in the Heaps menu. 


Memory, The debugging version’s memory blocks in 
the QuickDraw GX heap are a bit bigger to help detect 
errors w^hen your appEcation writes over the end of a 
block: all the blocks end with the same signature, 'grfe’. 

Special MacsBug messoges. The debugging version 
generates MacsBug messages that are intended solely 
for the consumption of the Apple engineers in unusual 
circumstances. (One of my favorites is ‘‘Curious if this 
ever happens.”) If we did our jobs right, you should 
never see one of these messages. In case you do, 
however, we’re really interested in hearing w^hat caused 
you to receive itj please let us know at AppleLink 
APPLE.BUGS. 

CLEANING UP 

You should design your applicarion to take advantage of 
the extensive capabilities of the debugging extension, 
but turn those capabilities off when you create your 
final shipping application, to improve its performance. 
For example, calling (iXValidateShape with the 
nondebugging extension installed will only result in a 
jump and return (that is, it will be a no-op). This is a 
wonderful method for testing the QuickDraw GX 
dispatcher, but it doesn’t help the performance of your 
application. 

In the final compile of your shipping application, you'll 
most likely want to remfwe all calls to validation 
routines, posting of notices, and extra w^arnings and 
errors available only in the debugging version. One 
approach would be to have various compilation flags 
associated with pairs of #ifdef and #endif to turn these 
features on and off. 

For more information, see my article in Issue 15 if you 
haven't already — or just dig into the QuickDraw GX 
documentation. Enjoy your journey into the 
QuickDraw GX world! 


RELATED READING 

• ^'Getting Started With QuickDraw GX" by Pete 
("Luke'') Alexonder, deve/op Issue 15. 

• "Print Hints: Looking Ahead to QuickDraw GX" by 
Pete ("Luke") Alexander, develop Issue 13. 


Thanks to Hugo Ayalo^ Cory Clork^ and Herb Derby for 
reviewing this column.* 
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Exploiting Graphics Speed on the 
Power Macintosh 



KONSTANTIN OTHMIR, 
SHANNON HOILAND. 
AND BRIAN COX 


The new QuickDraw on the P(rwe?TCplatform mbstantmlly improves 
gi^aphics pe?fof^mnce. A study compari?ig the pejfonnance of 
QuickDraw and custom blitters on the Power Macintosh and 680x0- 
based machines provides information you can use to ensure that the user 
benefitsfivm those impfwements. Further analysis, detailing where 
Copy Bits spends its time, leads to an implementatmi strnte^ for 
applica tions that demand the fastest possible ^nphks. 


Understanding the motivation for and consequences of the changes to QuickDraw on 
the Powder Macintosh can help you WTite faster applications. This article presents 
studies that show QuickDraw as one of the most speed-critical parts of the Macintosh 
Operating System togetlier with studies that break down how^ applications spend 
CPU time. Knowing how^ much dme applications actually spend in various system 
routines will help you develop a strategy for writing applications that perform well on 
both the Power Macintosh and 680x0-based machines. 

In porting QuickDraw to the PowerPC^^ platform, Apple took advantage of the 
opportunity to make some changes, Weil detail these changes and tlieir 
consequences for writing code. With that foundation, w^eil move on to an in-depth 
discussion comparing the QuickDraw CopyBits routine with custom blitters. The 
goal is to write applications using routines that result in the fastest possible graphics 
performance on both platforms — PowerPC and 680x0 — as well as on machines 
equipped with graphics accelerators such as the new Apple Macintosh Display Card 
24 AC. Sample code on this issue’s CD demonstrates a method of timing blitter 
routines so that your application can use the fastest routine at run time. 


HOW SPEED-CRITICAL IS QUICKDRAW? 

Most of die Macintosh Operating System is written in 680x0 assembly language. In 
order to reach rime-to-market goals for the Power Macintosh, Apple had to focus 
porting efforts on the most speed-critical parts of the system, so a study was 
conducted to profile system usage of several common applications. System usage 


KONSTANTIN OTHMER, SHANNON 
HOLLAND, AND BRIAN COX, who are 

always ready to explore new avenues in software 
development for the QuickDraw team^ hove 
finally hit the noil on the head. Their secret is 
high-tech equipment ond proper deiegaHon of 
work. Alternating between periods of sleep ond 
contemplation, they use telepathic communicotbn 
to transmit source code to each new team 


member, who can then look forward to many 
days of compile cycles on □ trusty Macintosh Plus 
(providing our authors with even more time for 
sleep and contemplation) ^ The team Is on the 
lookout for new labor-saving devices. Donations 
are welcome ^— comfortable couches to moke 
room for future expansion would be particularly 
appreciated." 
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depended largely on the operations performed in particular applications, hut many 
applications showed similar patterns. 

Figure 1 is based on a subset of the study. It turns out that most applications spend 
from 50% to 95% of their time in system code, with many spending more than 80%. 
Figure 2 shows the percentage of total CPU time spent in the most frequently called 
system routines for typical applications and for a pointer-based application (one that 
avoids using handles). 


Cricket Draw 1.1.1 
MacWrite II 
Mac Draw II 
Word 4.0 
PageMaker 4.0 
Super 3D 
Excel 2,2 



% In application 
□ % In Macintosh OS 


0 20 40 60 80 100 

% of Total CPU Time 


Figure 1- CPU time breokdown: application versus system 
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LineTo 
PaintRecl 
SetHandleSize 
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GetFonflrtfo 
I^GBBackColor 
DrawStrj'ng 
NewHandle 
SCSIDispeich 
FiliRgn 
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Typical applications (Cricket Draw 1.1.1, MaeWnte II, Pointer-based application (Super 3D) 

MocDraw If Word 4.0, PageMaker 4.0, Excel 2.2) 


Figure 2* System routine usage 

The data made it clear that QuickDraw was one of the most critical components of 
Apple’s porting efforts. This article discusses QuickDraw versicm 1.3.5, which was 
developed to run on the PowerPC platform. The new QuickDraw is based on 
QuickDraw version 1.3.0, the most recent version of QuickDravv running on the 
.Macintosh Quadra, but with some changes (see the section ^MTat’s Different M^th 
V^ersion 1.3.5?’’). The new version, written in C, was compiled for the Power 
Macintosh as QuickDraw version 1.3.5 and shipped with the new machines. The new 
QuickDraw^ C code can also be compiled for 680x0-based machines and will be 
available in future software releases. 

The graphics speed comparisons made in this article compare the following: 

• QuickDraw^ version 1.3.0 or other 680x0 code running on a 680x0- 
based Macintosh (usually a Alacintosh Quadra) 
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• QuickDraw version 1.3.0 or other 680x0 code running dirough 
the emulator on a Power Macintosh 

• QuickDraw version 1.3.5 or otlier PowerPC code running on a 
Power Macintosh 


TAKING ADVANTAGE OF THE SPEED 


Figure 3 compares rimes of various QuickDraw routines for version 1.3.0 running on 
a Macintosh Quadra and version 1.3,5 running on a Power Macintosh — there’s no 
question that the new^ QuickDraw routines run faster. However, published surveys 
comparing the speed of 680x0-based machines to the Power Macintosli haven’t 
alw^a)^ shown the dramatic results indicated by Figure 3. This is partly because some 
operations offer greater increased speed than others, so depending on which 
operations an application uses heavily overall speed varies. A second important factor 
is that the applications surveyed are often emulated applications. 


Line (vertical) ] 
Line (horizontal) [ 
line (slanted) j 
DrawTejd (bitmap) 
Drov^Text (outline) P 
FrameRect 


EraseRed 
Copy Bits bbit sre (targe) 
CopyBits 8-bit sre (smalt) 
CopyBlts S-bit sfc (large) 
PaintPoly 
DrawPicture 


dill' 






□ 
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Macintosh Quadra 700 (version 1.3.0) 
Power Mocintosh (version 1.3.5) 



0 5,000 

Note; Times are to an 8-bit screen. 


10,000 

Microseconds 


15,000 25,000 40,000 103,000 


Figure 3. Comparing QuickDraw version 1.3.0 to version 1.3.5 


Emulated applicarions are those wTitten for 680x0-based machines that run through 
the emulator on the Power Macintosh (see “Making the Leap to Pow^erPC,” develop 
Issue 16). These applicarions don’t benefit fully from the Pow erPC platfomi, because 
an application that spends 80% of its rime in system code on 680x0-based machines, 
when emulated on a Power Macintosh, spends substantially more time in the 
application. In general, completely emulated application code runs at about half the 
speed of a Alacintosh Quadra 700. Those same applications, when recompiled as 
PowerPC code, usually run four or five rimes faster than on a xMacintosh Quadra; 
code that makes extensive use of floating point may be 20 times or more faster. 
How^ever, emulated graphics-mtensive code, assuming it uses QuickDraw, is 
substantially faster on a Pow^er Macintosh than on a 680x0-based Alacintosh because 
of the increased speed of QuickDraw^ 1.3.5. 
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Clearly, to take full advantage of QuickDraw version 1 J.5, you need to write your 
applications for the Power Macintosh m PowerPC code. Beyond that general 
strategy, developing awesome applications for the PowerPC platform means figuring 
out how to harness all that CPU power — how to take advantage of the speed. For 
example, the high speed of QuickDraw version 13.5 allows you to do high-quality 
animations. Figure 3 shows that you can now do mice as many (or more) Copy Bits 
operations per second, which means chat animations such as zooming, scrolling, and 
window dragging (leave this one to Apple) can be done in real time without being 
chunky or annoying. Text drawing is also much faster, so interactive word wrapping 
while positioning objects in text is easy to do and looks better than it would on a 
680x0-based Macintosh. Overall, it’s an open field for developers. 

Tips for increosing the speed of PowerPC code ore given in fhis issue's Bobnce 
of Power column." 

Although this article focuses on QuickDraw, of course there are other, nongraphical, 
ways of harnessing the powder of the PowerPC processor. Floating point-intensive 
applications benefit tremendously from the speed of the new processor. 

The Graphing Calculator desk accessory thot ships with the Power Mocintosh 
is an excel lent example of harnessing CPU power br both the user Interface ond 
computatiorhbound port of on opplkation. As a floating point-intensive appllcarlon, 

Graphing Calculator benefits from the speed of the PowerPC processor. The user 
interface has a number of nice touches, such os live scrolling, live zooming, and 
Interoctive formub and graph monipulotion.* 


WHArS DIFFERENT WITH VERSION 1.3.5? 

In the porting of QuickDraw to the PowerPC platform, many algorithms were 
rethought and reimplementcd. The result is slightty different (and we hope better!) 
behavior. This section outlmes some changes to keep in mind when you’re writing 
code. 

QDERROR 

QuickDraw version 1 J.O didn’t do a very good job of setting and clearing QDError. 
In version 1.3.5, every call sets QDError {which can cause problems for applications 
that assume QDError will be preserved across most simple calls, like SetRect). In 
some cases, version 1.3.0 jumps to SysError if there isn’t enough memory; version 

1.3.5 returns an error in QDError instead. This is usually an improvement, but it can 
lead to strange behavior for applications that depend on SysError being invoked. For 
example, some applications might put up a dialog asking the user to increase the 
application partition size if QuickDraw invokes Sjj^Error. Since QuickDraw version 

13.5 doesn’t invoke SysError (returning a QDError instead), the application code 
til at puts up the dialog isn’t triggered, so the user doesn’t know to increase the 
memor)^ and the application might fail by not draw'ing anything. In choosing to 
always set QDError, Apple chose the lesser of two evils. 

MATCHING COLOR TABLES 

QuickDraw version 13.0 uses the color table of the pixMap for the current GDevice, 
not the color table of the destination pixMap, to map colors to the destination 
pixMap. QuickDraw^ version 1,3.5 sets up a surrfigate GDevice to make sure tliat the 
the destination pixMap’s and the GDevice’s color tables always match. This may 
cause problems for applicatians tliat relied on undefined behavior w^hen the color 
tables didn’t match or for applications chat were getting the right results by luck 
under QuickDraw^ version 13,0. Again, Apple chose the lesser of rw^o evils, and added 
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the surrogate device (known as the skank device). WTien QuickDraw is forced to set 
up the skank device, the application pays a slight perfomiance penalty. Also, if you do 
operations such as index-to-color when your color tables don’t match, and then later 
use that color in a drawing, you w^on’t necessarily draw wdth the index you expect. 
The easiest cure: use GWorlds! 

For more inlormation on QDError, GDevices, pixMops, and color tables, see 
tnside Macintosh: imaging With QuickDraw or inside Macintosh Volume V." 


TRANSFER MODES 

There's no way to pass the transfer space (the bit depth at w^hich transfer occurs) 
when doing transfer modes in QuickDraw. (QuickDraw GX remedies this 
shortcoming.) So if you're using an arithmetic mode from 8-bit to 16-bit, there are no 
guarantees whether the transfer will occur at 5 bits per component (16-bit), 8 bits per 
component (32-bit), or 16 bits per component (as in the 8-bit color table). It turns 
out that most arithmetic modes in QuickDraw version 1.3.0 perfonn the transfer 
operation at a resolution of 16 bits per color, w^hile version 1.3.5 does most operations 
at a resolution of 8 bits per color. Tliis sometimes causes slight cosmetic differences. 

DITHERING 

The dithering algorithm in QuickDraw version L3.5 is slightly different. This makes 
it a nightmare to programmatically determine whether version 1.3.5 is generating the 
same results as version IJ.O, bin visually the results are nearly identical. 

STRETCHING AND SHRINKING IMAGES 

The way Ck>pyBits stretches and shrinks images for nonintcgral ratios has been 
improved in QuickDraw version 1.3.5 (integral ratios still produce the same results). 
The advantage of this new^ algorithm is that it's symmetrical: if you stretch an image 
and then shrink it back to the original size, the same pixels diat were replicated in the 
stretch are combined in the shrink. 

The disadvantage of the new algoridim is that some applications stretch or shrink 
widiout knowing it (the classic off-by-one error, resulting in a destination rectangle 
that's smaller or larger than the source rectangle by one pixel). Such applications may 
now^ drop (or replicate) a different scan line. This can cause slight cosmetic blemishes 
in some applications, 

UNEXPECTED REGISTER CONTENTS 

Because QuickDraw^ version 1.3,5 runs PowerPC code, all emulated 680x0 registers 
are preserved across calls. Thus, applications tliat expect the contents of volatile 
registers (AO, Al, DO, Dl, D2) to contain specific values on exit fi’om a QuickDraw 
call will l)reak. (Conversely, don't rely on 680x0 registers being preserved, eidier!) 
There's one exception: for compatibility with some existing applications, CopyBits 
alw^ays sets DO to 0. 

PATCHING 

Patching any QuickDraw version 1.3.5 routine with 680x0 code degrades 
performance because of mode-switch overhead time. A mode switch occurs when a 
680x0 caller is calling PowerPC code, or vice versa. 680x0 patches on ShieldCursor 
are particularly expensive because ShieldCursor is called by nearly every QuickDraw^ 
drawing routine. 

For more mformotion on Jhe Mixed Mode Manager and mode switching, see 
"Making the Leap to PowerPC" in develop Issue 16.* 
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DISABLED ACCELERATOR CARDS 

QuickDraw^ version 1J,0 makes calls through many low-ievel {undocuinented) 
vectors. Version 1.3.5 doesn^t use these trap vectors, which disables most accelerator 
cards. Of course, tlie frame boffer on these cards continues to work. 

THE COPYBITS/CUSTOM BLITTER RACE 

A favorite developer sport is complaining about how slow Copy Bits is and writing 
custom blit loops to replace it. A favorite sport among QuickDraw^ engineers is 
working all night trying to speed up some part of CopyBits. This competition is 
healthy so long as speed-critical applications call the faster code. 

"Blitter" inforinally refers to any rouffne that moves meinory, usually visual 
inFormahon to the screen or on oFf-screen buffer; the operotion is called a 
These terms derive from the PDP-t 0 block tfonsFer instruction, BIT.* 

Through the years, Apple engineers have yearned for a way to get a substantial lead 
in the race with the speed-hungry speciakcase developer. The answer lies in the 
PowerMacintosh: raw 680x0 code runs substantially slower through the emulator, 
while QuickDraw version 1J.5 CopyBits takes advantage of the lightning-fast RISC 
processor. 

Figure 4 compares various ways of moving the memory used by an 8-bit, 32-by-32 
pixMap and an 8-bit, 400-by-400 pixMap to the screen. BlockMove gives a baseline: 
tlie typical amount of time needed to move that much raw memory. The 680x0 blitter 
is a custom blitter written for 680x0-based machines and emulated on die Power 
Macintosh. The PowerPC blitter is a custom blitter WTitten for the Power Macintosh 
(it can^t be run on a 680x0 machine). 
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Figure 4- CopyBits versus custom blitters 


As you can see, the custom PowerPC blitters beat QuickDraw's CopyBits for the 
small image hands down for both 680x0-based machines and the Power xMacintosh. 
(M^th the small image the constant overhead of CopyBits has a big impact on the 
overall time.) However, the 680x0 blitter is much slower than CopyBits on a Powder 
Macintosh. This is due to the ewerhead of emulaticjn. 
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The interesting case is the custom PowerPC blitter versus CopyBits for the large 
image on the Power Macintosh. Here CopyBits wins. This is due to optimisations 
that CopyBits has for large images that the PowerPC blitter doesn't have. In this case, 

















































CopyBits is also faster than BlockMove, because of optimizations Ln CopyBits for the 
PowerPC processor's frame buffer (which has a 64-bit data path). BlockMovc is 
optimized for copying to main memory, so it's slower when copying to the frame 
buffer. (This is w^hy the PowerPC blitter is faster than BlockAlove for die small 
image.) If you compare BlockMove and CopyBits using an off-screen pixAlap as die 
destination, you discover that BlockiVIove is fasten 

For maximum performance of emuloted applications, the emulator treats 
BlockMove os o special case. * 

The design of a frame buffer can have a great impact on overall blit speed. These 
times were measured on the on-board video for the Macintosh Quadra and a fast 
processor-direct slot video card for the Power Macintosh. If you install a NuBus^''’ 
frame buffer on bodi machiiies and do a similar comparison, you find that the 
difference in times is Ie>ss. That’s because NuBus is the bottleneck for the copy 
operation. The situation changes radically, how'ever, if the NuBus card is accelerated. 
Then only calls to CopyBits get the acceleration; custom blit loops are still 
bottlenecked by NuBiis transfer rates. 

Most of the comparisons in rhis sec Hon compare raw memory-moving power. 

While QuickDraw is efficienl aJ streJching biJs, Ws very inefficient at large indexed 
shrinks. The problem is that CopyBits looks at every pixel and preserves the highest 
index value. (This was done so that when icons are shrunk, they don't inadvertently go 
to solid white,) For a shrink by o factor of four, this means that CopyBits is looking at 
16 times too much data. * 


REDUCING QUICKDRAW OVERHEAD 

There are mo aspects to any given QuickDraw operation: setup and actual drawing. 
Much of die time saved wdien an application uses a custom blit loop instead of 
CopyBits is a consequence of avoiding the overhead of QuickDraw’s setup. VVTile 
QuickDraM^ has extremely efiicient blit routines, its downfall is diat it has no idea 
bow it’s going to be called from one time to the next, so it has to do all the semp 
eveiy^ time it’s called. (See ^‘Drawmg in GWorlds for Speed and Versatility” in develop 
Issue 10 for a discussion of QuickDraw’s semp.) 

A.n application knows exacdy how many of what it’s drawing to where, so it can do 
the semp for many operations once at the beginning, use custom blitters to do the 
drawing, and then restore eveiy'^thing to its previous condition at the end, thus 
eliminating much of the setup time. This is w^here you get the biggest gains w hen 
writing your own blitters. On large operations, the overhead is relatively small, so you 
don’t gain much with custom routines. Small operations are often dominated by setup 
time, so a custom routine can improve performance significandy. 

Figure 5 compares semp time to total time for two CopyBits operations. Bodi are a 
copy of a 32-by-32, 8-bit, off-screen pixMap to the screen (no stretching or 
shrinking, long aligned). The difference is that in the first CopyBits call, the color 
tables match and in the second call they don’t match (the first case is faster because 
there’s no need to invoke a pixel translation loop). Figure 6 shows the same two tests 
as Figure 5, but this time the pixMaps being copied are 400-by-40(). If you look 
careMy, you can see that the setup time remained almost the same, but the 
proportion betw^een setup time and total time has changed drastically. 

In general, the setup time on the Power Macintosh is minimal, since the setup is 
computation-intensive and doesn’t depend on memory access. Remember that setup 
time is constant — it remains the same no matter how much data is being copied. 
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Figure 5. Copy Bits setup time to total time for a small copy 
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Figure 6. CopyBits setup time to total time for o large copy 


Therefore, the rekitive efficiency of CopyBiis depends on die innount of data being 
copied. 

The systems compared in Figures 5 and 6 are a Power Macintosh 8100/80 running 
QuickDraw version 1 J.5 and a Macintosh Quadra 700 running QuickDraw version 
L3.0. These coniparisons shim diat QuickDraw blit times can vary greatly across 
diflferent machines and different versions of QuickDraw, 

QuickDraw GX uses caches extensively to keep intermediate results. This allows 
part of the overhead to be short-circuited when a similar operation is performed 
multiple times. • 

Accelerator vendors use a number of different strategies for boosting QuickDraw’s 
performance. The Macintosh 8*24 GC card attempted to accelerate entire operations, 
while most third-party accelerators just concentrate on the blits. These cards often 
use custom chips to substantially increase the speed of writing to memory^ youVe still 
forced to pay for the setup time, but the blit time decreases substantially 

The upshot of this is that youVe only guaranteed the best results if you profile the 
candidates and pick a winner at run time. This is the topic of the following section. 
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STRATEGY FOR SPEED-CRITICAL APPLICATIONS 

For appliestiom in which speed is critical, you want to run as fast as possible on every 
machine. The easiest way to do this is to time the sy^stem code and any custom cotie 
and use the I aster version, perhaps even on a call hy call basis. By comparing the 
speed of a custom implementation with the Ibolbox implementation and picking die 
faster one at application initialization time, applications can automatically take 
advantage of hardware accelerators when they exist, or highly specialized custom blit 
loops when required. Of course, you would use this strategy only when speed is 
extremely important. While developing your application, you should always try to use 
system calls when they’re available before reinventing (a sometimes square) wheel. 

Listing 1 shows two routines, 71meBlitProc and BestBlitter, that compare CnpyBits 
with a custom blitter and return the address of the faster routine. (The code is also on 
this issue’s CD.) Writing the custom blitter is left as an exercise for the reader. 

BestBlitter takes a pointer to a BUtProc, a PixMapllandle, and a source and 
destination rectangle and returns the address of the faster routine ^— the custom 
BlitProc or ("opyBits. It assumes that the destination rectangle is for the current 
graphics port and current C^Device. For the sake of simplicity, the mode is assumed 
to he sreCopy and there’s no mask region. 

BestBlitter gets the address of CopyBits {factoring out tra[) dispatch overhead if 
mnning on a 680x(Lbascd Macintosh, as you might want to do in your speed-critical 
loops) and calls TimeBlitProc to get the time taken by each of tlie calls. If the 


Listing 1, Timfng routines 

tinclude <Tiiner,h> 
it include <FixMath.h> 

Iinclude <Traps,h> 
fif pcwere 

extern QDGlobala qd; 
iendif 


// Decide how many microseconds represent a "meaningful" difference. 

#define kHeaningfulDiff 0 

idefine ABS{x) {{k < 0)? (-x) ! {x)) 

unsigned long TimeBlitProc(BlitProePtr theBlitProc, BitMapPtr srcBits, 
BitMapPtr dstBits, Rect *srcRect, Rect *dstRect, short mode, 
RgnHandle mask) 

{ 

Unsignedwide startMicroSec, endMicroSec? 


Microseconds(&startMicroSec); 

(^theBlitProc)(srcBits, dstBits, srcRect, dstRect, mode, mask); 
Microseconds(&endMicroSec); 

// WideSubtract isn't defined for 680x0-based machines; however, a 
// version is included on the CD. 

Wide S ub t rac t[( wide * ) & endMi c ro Sec, {wide *} S s t artMicroSec ) ; 
return endMicroSec*lo; 


(confmued on next page) 
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Listing 1* Uming routines (confinued) 

SlitProcPtr Be5tBlitter(BlitProcPtr customfllitProc, 

PixMapHandle srcPixHandle, Rect ^srcRect, Rect *dstRect) 

{ 

unsigned long customBitsTime, copyBitsTime; 
long leDif f erence ; 

PixHap Band1e por tPixMap; 

BlitProcPtr copyBitsPtr; 

Str255 nuinStr; 

//To factor out the trap overhead, get the trap address for CopyBits, 
// PowerPC can get the address of the shared library routine directly* 
// By getting the address of the library routine like this, we don't 
// need to worry about calling CopyBits through CallUniversalProc. 
iif powerc 

copyBitsPtr = (BlitProcPtr) tCopyBits; 

#else 

copyBitsPtr = (BlitProcPtr) GetToolTrapAddress(^CopyBits); 
lendif 

portPixMap = ((CGrafPtr) qd,thePort)->portPixMap ? 

// Kloririally, it's not necessary to lock a pixMap or its pixels before 
// calling CopyBits. But in this case, we're calling TimeBlitProCr 
// which could hit the Segment Loader and cause memory to move. So we 
// lock the pixMap handles before dereferencing them here. 

HLoc k([H and1e) portPixMap); 

LockPixels(portPixMap}; 

copyBitsTime - TimeBlitProc(copyBitsPtr, 

(BitMapPtr) *srcPixEIandle, (BitMapPtr) *portPixHap, srcRect, 
d stRect, s rc Copy, nil}? 
customBitsTime = TimeBlitProc(customsLitProc, 

(BitMapPtr) *srcPixHandle, (BitMapPtr) *portPixHap, srcRect, 
dstRect, srcCopy, nil); 

UnlockPixels(portPixMap); 

HUnlock((Handle) portPixMap); 

leDifference = (long)(customBitsTime - copyBitsTime); 
if (ABS(leDifference) > kMeaningfulDiff leDifference < 0) 
return customBlitProc? 
else 

return copyBitsPtr; 


difference is enough to be meaningful (more than a feM^ micrnseconds) and favors the 
new BlitProc, BestBlitter returns a pointer to the BlitProc; otherwise, it returns a 
pointer to CopyBits, 

The actual timing is done by Time BlitProc, which assumes chat the current graphics 
port and GDevice are set up and ready for copying, TimeBlitProc takes a pointer to 
the BlitProc to be timed and a list of arguments expected by CopyBits. 

WeVe made the assumption that the caller has Hushed or loaded the caches 
appropriately for the test. In comparing the routines, it w^ould be unfair to one 








routine if it had to spend time loading the data intti the cache and the other routine 
didn^t! Fiushinstmcri on Cache and FlushDataCache are no kinger avaiiahie for 
applications written in PowerPC code, so it’s up to the caller to decide whether to test 
these BlitProcs cached or uncached. {See “Here’s the Cache” for a discussion of 
caching on the Power Macintosh.) In any case, TimeBlitProc assumes tliat the caches 
are already in the proper state. 

Since caching is such a hardware-specific operation and can have both very obvious 
and subtle effects on the execution of your code, it’s hard to predict how different 
cache architectures will affect your performance. In general, if you try to optimize for 
smaller caches, you’ll achieve better overall perfonnance across a range of platfonns. 
To be completely fair, TimeBlitProc should also disable interrupts. If file sharing 
comes in to work on a background copy in the middle of the timing, that blit loop 
will appear to be really slow compared to die uninterrupted time. 


HERE'5 THE CACHE 


The traps FlushInstructionCache and FlushDatoCache 
were originally created to give direct control over the 
instruction and data caches on 68040-based Mocinfosh 
Quadra models. These two traps are very closely tied to 
the 68040 processor, both conceptually and in their 
implementation. The PowerPC 601 chip has a unified 
cache ™ o single 32K cache for both data and 
instructions. Rather than frying to contort the definition of 
the two existing traps to moke sense on the PowerPC 
processor, Apple engineers asked why you need to flush 
caches in the first place. The new cache-management 
strategies ore intended to be better abstrocted, less 
dependent on o specific processor, and definitely forward 
compotible. 

Following ore the four main reasons you might want to 
flush the caches and how theyVe been (or need to be) 
addressed on the Power Macintosh. 

Generate code dynamically. 

Normally, to execute some data os instructions, you need 
to flush the caches. On the Power Macintosh, you call the 
new system routine MakeDataExecutable, passing the 
base address and the length of the data to be executed. 
(This routine doesn't exist—^ even in an undocumented 
form — on the 680x0-based machines, so to flush 
instructions in the data cache, you need to call 
FlushInstructionCache and FlushDatoCoche.) 

Ensure that the data shared by other hordware 
is actually written* 

For example, memory that's shared by a coprocessor 
has to be accessible when the other processor needs to 
read it. To address this problem, the PowerPC-Family 
architecture includes a type of '^bus snooping," Whenever 
someone wants to read an address thafs represented in 
the cache, the cache is flushed automatically before the 


data is returned. This way, you don't need to onticipote 
all the different ways the cache can get out of sync. 

Ensure that data gets written to memory in the 
correct order. 

For example, if you're writing to the screen, moke sure the 
title bar gets written before the contents, A caching 
mechanism could screw up this ordering, so to ensure the 
proper ordering, the data cache must be flushed between 
writes. Screen memory is marked os write-through, which 
sends the data to the cache and on through to the screen 
memory. Writes tor write-through memory are as slow as 
tor uncoched memory. The benefit is that reads from write- 
through memory can still take advantage of the cache. 

This feature Is present on the 68040 Macintosh and 
remains unchanged on the Power Macintosh . 

Ensure thot timing data you get when you 
compare two similar routines hasn't been 
distorted by the caching mechanism. 

Unfortunately, you're out of luck here. There's no officially 
sanctioned method for doing this. But there are some 
techniques you can use to get around the caching. 

If you anticipate thot your procedure will usually have its 
data cached when it's called, compare the routines for the 
cocbed condition. Simply call the routines twice and time 
only the second coll. 

To compore the routines for the noncoched cose, you con 
"flush" the cache by reading every byte in a 32K buffer. 
Not only is this ugly, but it's not even guoronteed to work 
with future machines (such as the PowerPC 603, which 
goes bock to using separate data and instruction caches). 
And even on the 601 chip, this would flush only the on- 
chip cache; it wouldn't necessarily flush the much lorger, 
but slightly slower, external cache. 
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1 inieBlitProc calls a new trap, ^Microseconds, that takes a pointer to an 
UnsignedMlde {t^^o longs) and fills it with the number of microseconds that have 
elapsed since the system was booted. It calls Microseconds before and after the call to 
the BlitProc that was passed in, calls WideSubtract to get the delta, and returns the 
kw-order 32 hits of the subtraction. This assumes that the elapsed time will fit into 
an unsigned long, or that the BlitProc will take less than 71 minutes to complete! 

OFF AND RUNNING 

The Power Macintosh provides a new range of computing power for the next 
generation of the Macintosh Une, The challenge for Apple is converting from a 
largely 680x0 assembly code base to PowerPC-code system services and substantially 
improving the user experience in the process. The challenge for application 
developers is inventing new uses for all the power provided hy RISC, and designing 
creative user interface elements that take advantage of the h<]rsepower. 

Use the studies presented here as a guide to writing graphics-in tensive applications 
that shine on both platforms. By using techniques such as runtime determination of 
che most efficient routines, you can guarantee that your application will get the most 
out of the system today and in the future. 


Thanks \o our technScol reviewers lew Cirne, and \o Tom Adams, Becky Hommoker, Mortanne 

Jeon<Ihorles Mourey, Guillermo Ortiz, ond Andy Hsiung, Mac MocDougoll, ond David Seorles br 

Stadler; to Kate Cremer for generating the grophs; conducting the application evaluotions.* 


We're looking for developers to join us in creating the 
next generation of innovative computing products 
and services. 



^Ith a market of more than 13 million customers worklwicle, Apple 
continues to outpace the industry in unit growth. As Macintosh application 
units continue to grow, Apple offers developers the licst platform for 
sustained growth. 

At Apple, we know that our success depends on providing our developers 
with die programs and resources needed to create great products anti 
services. Join our community of develoiters and receive answers to 
technical questions; stay informed of special Apple evencs; and 
communicate with Apple, fellow developers, and customers. 

For more information on the suppon and services offered through Apple’s 
developer progi'ams contact: 

Apple Computer, Inc. 

Developer Suppon Center 
20525 Mariajai Avenue, M/S 303-2T 
Cupertino, CA 95014 
{408} 9744897 


54 develop Issue SB June 1994 











DAVE EVANS 


BALANCE OF 
POWER 

Enhancing 
PowerPC 
Native Speed 


W^en you convert your applications to native 
PowerPC code, diey run lightning fast. Tc> get the most 
out of RISC processors, however, you need to pay close 
attention to your code structure and execution. Fast 
code is no longer measured solely by an instruction 
timing cable. The PowerPC 601 processor includes 
pipelining, multi-issue and speculative execution, 
branch prediction, and a set associative cache. All these 
tilings make it hard to know^ what code will run fastest 
on a Pom er Macintosh, 

Writing tight code for the PowerPC processor isn’t 
hard, especially with a good optimizing compiler to 
help you. In this column Fll pass on some of wdiat Fve 
learned about tuning PowerPC code. There are 
gotchas and coding habits to avoid, and there are 
techniques for squeezing the most from your speed- 
critical native code. For a good introduction to RISC 
pipelining and related concepts that appear Ln this 
column, see “Making the Leap to PowerPC’’ in Issue 16. 

MEASURING YOUR SPEED 

'The power of RISC lies in the ability to execute one or 
more instructions every machine clock cycle, hut RISC 
processors can do this only in the best of circumstances. 
At their w^orst they’re as slow^ as CISC processors. The 
following loop, for example, averages only one 
calculation every 2.8 cyxies: 

float atL btL c[], d, e; 
for {i-0; i < gArraySize; i++) { 
e = b[i| + c[il / d; 
a[i] = MySubroutine(b[i], e); 

} 


By restructuring the code and using other techniques 
from this column, you can make significant 
improvements. This next loop generates the same 
result, yet averages one calculation ever\^ 1.9 cyd^s — 
about 50% faster. 

reciprocalD = 1 / d; 

for (i=0^ i < gArraySi^e; i+=2) { 

float result, localB, locale, localEj 
float result2, localB2, localC2, localE2; 

localB - b[i]; 
locale = c[i]; 
localB2 “ b[i+l]? 
localC2 “ c[i+i]r 

localE - localB + (localC * reciprocalD); 
localE2 = localB2 + {loGalC2 * reciprocalD); 
InlineSubroutine(&result, localB, localE); 

IniineSubroutine[ & result2, localB2, localE2); 

a[i] = result; 
a[i+l] ^ result2; 

> 

The rest of this column explains tbe techniques I just 
used for that speed gain. They include expanding loops, 
scoping local variables, using inline routines, and using 
faster math operations. 

UNDERSTANDING YOUR COMPILER 

Your compiler is your best friend, and you should try 
your hardest to understand its point of view. You 
should understand how it looks at your code and Mdiat 
assumptions and optimizations it’s allow'ed to make. 

The more you empathize with your compiler, the more 
you’ll recognize opportunities for optimization. 

An optimizing compiler reorders instructions to 
improve speed. Executing your code line by line usually 
isn’t optimal, because the processor stalls to wait for 
dependent instructions. The compiler tries to move 
instructions that are independent into the stall points. 
For example, consider this code: 

first = input * numerator; 
second = first / denominator; 
output = second + adjustment; 


DAVE EVANS may be able to tune PowerPC code for Apple, but 
for the last year he"s been repeatedly thwarted when tuning his 
1978 Horley-Dovidson XLCH motorcycle. Fixing engine stalls, poor 
timing, end rough storts proved difficult but he wos recently 
rewarded with the guttural purr of q well-tuned Harley, * 


Code exomples were compiled with the PPCC compiler using 
the speed optimization option, and then run on □ Power Macintosh 
61CX)/66 for profiling. A PowerPC 601 microsecond timing library 
is provided on this issue's CD.* 


BALANCE OF POWER: ENhtANCING POWERPC NATtVE SPEED 55 









Each line depends on the previous line’s result, and die 
compiler will be hard pressed to keep the pipeline full 
of useful work, This simple example could cause 46 
stalled cycles on die PowerPC 601, so the compiler will 
look at other nearby code for independent instructions 
to move into the stall points. 

EXPANDING YOUR LOOPS 

Loops are often your most speed-endcal code, and you 
can improve their perfonnance in several W'ays, Loop 
expanding is one of the simplest methods. The idea is 
to perform more dian one independent operadon in a 
loop, so that the compiler can reorder more work in 
the pipeline and thus prevent the processor from 
stalling. 

For example, in this loop there’s too little work to keep 
the processor busy; 

float a[J, bf], c[], d; 
for (i=0; i < multipleOfThree? i+t) { 
a[i3 = b[i] + c[i] * d? 

} 

If we know the data always occurs in certain sized 
increments, we can do more steps in each iteration, as 
in the following: 

for (i=0j i < muItipIeOfThree; i+=3) { 
a[i] = b[i] + c[i] * d; 
a[itl] = b[i+l] + c[i-M] * d; 
a[it2] = b[it2J + c[i-H2] * d; 

} 

On a CISC processor the second loop wouldn’t be 
much faster, but on the PowerPC pn^cessor the second 
loop is twice as fast as the first. This is because the 
compiler can schedule independent instructions to keep 
the pipeline constandy moving. {If the data doesn’t 
occur in nice increments, you can still expand the loop; 
just add a small loop at the end to handle the extra 
iterations.) 

Be careful not to expand a loop too much, though. Very 
large loops won’t fit in the cache, causing cache misses 
for each iterarion. In addition, the larger a loop gets, 
the less work can be done entirely in registers. Expand 
too much and the compiler w ill have to use nmnmy to 
store intermediate results, outweighing your marginal 
gains. Besides, you get the biggest gains from the first 
few expansions. 

SCOPING YOUR VARIABLES 

If you’re new^ to RISC, you’ll be impressed by the 
number of registers available on the PowerPC chip — 


32 general registers and 32 floating-point registers. By 
having so many, the processor can often avoid slow 
memory operations. Your compiler will take advantage 
of this w'hen It can, but you can help it by carefully 
scoping your variables and using lots of local variables. 

The ''scope” of a variable is the area of code in w'hich it 
is valid. Your compiler examines the scope of each 
variable when it schedules registers, and your code can 
provide valuable information about the usage of each 
variable, Here’s an example: 

for (i“0; i < gArraySize; i++) { 

a[i3 - MyFirstRoittine(b[i] ^ G[i3); 
b[i3 - MySecondRoutine(a[i], c[iJJ; 

} 

Li this loop, the global variable gArraySize is scoped 
for the whole program. Because we call a subroutine in 
the loop, the compiler can’t tell if gArraySize will 
change during each iteration. Since the subroutine 
might modify gArraySize, the coiujiiler has to be 
conservative. It will reload gArraySize from memory on 
every iteration, and it won’t optimize the loop any 
further. Phis is wastefully slow. 

On the other hand, if w'e use a local variable, w^e tell the 
compiler that gArraySize and c[i] won’t be modified 
and chat it’s all right to just keep them handy in 
registers. In addition, we can store data as temporary 
variables scoped only within the loop. This tells the 
compiler how we intend to use the data, so that the 
compiler can use free registers and discard them after 
the loop. Here^ w^hat this wmild look like: 

arraySize = gArraySize; 
for (i-O; i < arraySize; i++3 { 
float locale; 
locale “ c[i]; 

a[i] == MyFirstRoutine(b[i], localG); 
b[i] = MySecondRoQtine(a[i]p locale); 

} 

These minor changes give the compiler more 
infonnation about the data, in this instance accelerating 
the resulting code by 25%, 

STYLING YOUR CODE 

Be w ar)" of code that looks complicated. If each line of 
source code contains complicated dereferences and 
typecasting, chances are the object code has w^astefiil 
memory instructions aaid inefficient register usage. A 
great compiler might optimize well anyway, but don’t 
count on injudicious use of temporary variables (as 
mentioned above) will help the compiler understand 
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exactly what youVe doing — plus your code will be 
easier to read. 

Excessive memory dereferencing is a problem 
exacerbated by the heavy use of handles on the 
Macintosh. Code often contains double memory 
dereferences, which is tniportant w^l^en memory can 
move. But when you can guarantee that memory^ won^t 
move, use a local pointer, m that you only dereference 
a handle once. This saves load instructions and allows 
further optimizations. 

Casting data types is usually a free operation — youTe 
just telling the compiler that you know' you’re copying 
seemingly incompatible data. But it’s not free if the data 
types have different bit sizes, w'hich adds conversion 
instructions. Again, avoid this by using local variables 
for the commonly casted data. 

Tve heard many times that branches are “free” on the 
Pow^erPC processor. It’s true that often the pipeline can 
keep moving even though a bnmch is encountered, 
because the branch execution unit will try to resolve 
branches very early in die pipeline or will predict the 
direction of the branch. Still, the more subroutines you 
have, the less your compiler will be able to reorder and 
intelligently schedule instructions. Keep speed-critical 
code together, so that more of it can be pipelined and 
the compiler can schedule your registers better. Use 
inline routines for short operations, as I did in the 
improved version of die first example loop in this 
column. 

KNOWING YOUR PROCESSOR 

As with all processors, the PowerPC chip has 
performance tradeoffs you should know about. Some 
are processor model specific. For example, the 
PowerPC 601 has 32K of cache, while die 603 has 16K 
split evenly into an instruction cache and a data cache. 
But in general you should know" about floating-point 
performance and the virtues of memor\" alignment. 

Floating-point multiplication is wicked fast — up to 
nine mnes the speed of integer multiplication. Use 
floating-point multiplication if you can. Floating-point 
division takes 17 times as long, so when possible 
multiply by a reciprocal instead of dividing. 

Memory accesses go fastest if addressed on 64-bit 
memory boundaries. Accesses to unaligned data stall 
while the processor loads different words and then 
shifts and splices them. For example, be sure to align 
floating-point data to 64-bit boundaries, or you’ll stall 
for four cycles wEile the processor loads 32-bit halves 
wdth two 64-bit accesses. 


MAKING THE DIFFERENCE 

Native PowerPC code runs really fast, so in many cases 
you clon’t need to worry about tweaking its 
performance at all. For your speed-critical code, 
though, these tips I’ve given you can make the 
difference betw^een “too slow” and “fast enough.” 


RECOMMENDED READING 

• High-Performonce Computing by Kevin Dowd 
(O'Reilly & Associotes, Inc., 1993). 

• High-Performance Computer ArchHecfure by 
Harold S. Stone (Add I son-Wesley 1993), 

• PowerPC 601 RISC Microprocessor User's 
Monuo/(Motorola, 1993). 


Thanks to Nick Kledzik, Andy Nicholas, and Dove Radcfiffe br 
reviewing this column.* 



Power up with 
PowerPC 


Apple Developer University has just 
what you need to jump start your PowerPC 
development efforts. 


• Programmers Introduction to RISC and 
PowerPC self-paced training 

• PowerPC BootCamp 

For more information, contact the Developer 
University Registrar at (408) 974-4897, 
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Displaying Hierarchical Lists 


Much of the data you manage on a Macintosh has a hierarchical 
nature. This article shows how your application can provide a clear^ 
coherent data organization with a user-controlled display by using 
classic linked lists^ storing the list data in handles, and displaying it 
with the List Manager. A triangular button mechanism, similar to 
that used in the Finder to open and close folders in list views, lets the 
user decide how much data to view on the screen. 



MARTIN MINOW 


If your application makes its hierarchical data accessible but not overwhelming, it will 
have an advantage over applications that provide only two alternatives — -'throw it all 
on the screen” or “hide everything*” You can find many examples of flexible 
organization! The Finder presents file and folder information in a variety of display 
formats revealing mom or less information according to the user’s own desires* 
Document-based applications such as NewsWatcher provide a hierarchy of text 
information. The JMP statistical application provides buttons that reveal more 
detailed infimmation about an analysis. Programming languages such as Frontier 
allow the programmer to display as much of a module’s code as is needed* 

This article shows how to do the following: 

• store hierarchical data in a linked list along with the inffirmation 
needed to display it properly 


• extend the List Manager by storing a button object in a List 
Manager cell that controls how the data hierarchy is displayed 

• build the data hierarchy and display it 


• let the user manipulate the buttons to view more or less of the data 


The accompanying code on this issue's CD includes a sample library that stores data, 
displays it, and manages the buttons, and a simple application that uses tiie library* 
The techniques described in the article are appropriate for displaying and organizing 
moderate amounts of data; they’re less useful for static data or large amounts of data 
and are inefficient with small amounts of data. 


MARTIN MINOW (AppleLink MINOW, Internet 
mino\v@apple.com) is on oged^ wrinkled hacker 
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bits long, ond o supercomputer hod 1024 of 
them. In reol life, he works ot Apple's Developer 
Support Center, drinks beer, and runs 
marathons.* 


58 


develop Issue 1B June 1994 









Figure 1 shows a Finder-iike window that was created \vixh this lilirary; the files 
displayed are from the sainpie library, IVe called the libraiy^ Twist Down to emphasize 
how the display acts when you click the buttons. The Finder development team calls 
the buttons nimgiikr kimns. 


List in a Handle in a List 


Desktop DF 
|>De3k1op Folder 
Hill Effect For Regression 
Icon 

v^List i n a Handle Article 9/23 j 
Closed Triangle 
Closed Triangle Polygon 
Figure 1 
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Window Me negerx 
Minow,draft2^‘mm 
Open Triangle 


Figure 1, Window created with TwistDown library 


STORING DATA IN A LINKED LIST 

There isn’t much in this article on linked lists or handles; I assume you struggled with 
■^classical’^ list processing when you learned to program and have done enough 
programming on the Macintosh to understand how handle-based storage operates. 
Keep in mind that two kinds of lists are discussed here- Unked lists and Macintosh 
List Manager display lists. To keep confusion to a minimum^ element refers to a 
component of a linked list and cell refers to a component of a List Manager list Note 
also that linked lists contain the data, while the List Manager list only controls the 
appearance of that data, A good understanding of the List ATanager is needed to 
follow the code examples later in the article. (For details on the List Manager, see 
Inside Macintosh: More Madmosh Toolbox, or Inside Macintosh Volume IV,) 

In the context of this article, a list element is a chunk of data, a few flags, and two 
linkages. This section discusses the linkages, which connect list elements into 
sequences and hierarchies, and the creation and disposal of list elements. The flags, 
w^htch simplify formatting the data, are discussed later in the section '‘Controlling 
Data Appearance.” 

Figure 2 illustrates the linkages that connect list elements. The important thing to 
remember about the hierarchical linked lists weVe using is that any element may have 
a sticcessor — the sibling element that follows it — and a descendant — a child element 
that begins a lower level of the hierarchy. For example, a document outline has a 
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sequence of chiipters (siblings) and each chapter has, as its descendants, a sequence of 
sections. 


Elerrent 1 Elemenf 3 (sibling ebment) 



Figure 2. List element orgonizaHon 


Jn the sample code, each list element is stored in a handle. This allows the Memory 
Manager to reorganize memory lo store data efficiently. However, don’t forget diat 
the application program is responsible for disposing of data that’s no longer needed. 

Two library Rmctions manage the list elements: Make1 WistDownlilement creates an 
element and connects it to the list hierarchy anti DisposeTwistDownEleinent deletes 
an element along wndi its descendants and successors* 

CREATING A LIST ELEMENT 

lasting I shows the definition of our element structure, IwistDownRecnrci Each 
field of this structure will be explained as it’s encountered in the sample code. 


Listing 1. TwistDownRecord 





struct TwistDownRecord { 

struct TwistDowuRecord 

* *nextElement; 

/* 

”> successor element 

*/ 

struct TwistDownRecord 

**subEleitLentf 

/* 

-> descendant element 

*/ 

short 

indentLevel; 

/* 

Indentation depth 

*/ 

unsigned short 

flag; 


Control flags 


unsigned short 

dataLength; 

/* 

Actual data length 


unsigned char 

data[l]; 

/* 

Data to display 

*/ 

/ f 

typedef struct TwistDownRecord TwistDownRecord, 

*TwistDownPtr, **TwistDownHandle; 



MakeTwistDowmElement (Listing 2) is called with the data to store in the element 
and a handle to its predecessor. The predecessor is eitlier NULL (3r the previous 
(elder) sibling element. For example, when creating element .1 in the list shown m 
Figure 2, the previous element is element 1, 

Tw'istDownRecord is a variable-length structure and Newd handle creates an inst ance 
that’s large enough to hold the caller’s data record. The strucmre definition, how^ever, 
contains one bit of trickery diat’s required by the ANSI C standard — it must specify 
at least one byte for the data[] placeholder. This is why the parameter to NewHandle 
adjusts the handle size to eliminate the extra byte. 
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DISPOSING OF A LIST ELEMENT 

The DisposeTwistDownHandte fiinction disposes ot a list element and then disposes 
of its descendant and successor lists. To dispose ol an entire list, call this function 
M ith the first list elejnent. 

A simplified version of DisposeTMistDownHandle is shown in Listing 3. The library 
implementation allows the application developer to specify a function thafs called 
when disposing of each element in the list. This is needed if an application has to 
store complex structures — themselves containing Per or Handle references — in a 
TwistDownHandle, 


Listing 2. MakeTwi stDown E lement 


OSErr MakeTwistDownE1ernent(TwistDownHandle 

short 

unsigned short 
Ptr 

TwiStDownHandle 

{ 

Twis t D ownHandle twistDownHandle? 


previousElement, 
indentLevel, 
dataLength, 
dataPtr, 

^result) 


twistDownHandle = (TwistDownHandle) NewHandle(siseof(TwiatDownRecord) 
- siseof(unsigned char) t dataLength); 

*resnlt = twistDownHandle; 
if (twistDownHandle i= NULL) { 
if (previousElement I- NULL) 

(* * p reviou s Element)* ne x tE1ement = twis t DownH a nd1e; 
(**twistDownHandle)*nextEleraent = NULL; 

{* twi s t DownHa nd 1 e), s ubE 1 ement = NULL; 

{**twistDownHandle),indentLevel - indentLevel; 

{**twistDownHandlej,flag = 0; 

(**twistDownHandle).dataLength - dataLength; 
if {dataPtr NULL) 

BlockMove(dataPtr, (**twistDownHandle),data, dataLength); 

> 

return (MemError{)); 


Listing 3* Disposelwi stDown Handle 

void DisposeTwistDownHandle{TwistDownHandle twistDownHandle) 

{ 

TwistDownHandle nextElement, subElement; 

while (twistDownHandle I- NULL) { 

nextElement = (**twistDownHandle).nextEiement; 
subElement = (**twistDownHandle).subElement; 

DisposeHandle{(Handle) twistDownHandle); 
if (subElement 1= NULL) 

DisposeTwistDownHandle{subElement); 
twistDownHandle = nextElement; 

> 

> 
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Note th-^t DisposeTwistDownHandle is a recxirsive function; it calls itself to dispose 
of the descendants of a hierarchy. If it^s called with the list shown in Figure 2, it 
disposes of elements in the order 1, 2, and 3. 

Using recursion simplifies the list-manogement olgortthms in theTwistDown function 
library. However, it's not without its pitfalls in the real world. Eoch time o function such 
as DisposeTwistDownHandle encounters a subelement list, it colls itself to dispose of 
that list, ond each of these colls uses stack space. While this isn't usually a problem 
for applications, you should avoid recursive algorithms in device drivers or other 
no nap plication code segments because they must work within the constraints of some 
other application's stack. * 


CONTROLLING DATA APPEARANCE 

Once the data in organized as a hierarchical listj the applicadon could simply display 
the whole list by just storing handles to the list elements in List Manager cells. 
However, if your application lets the user control how much of the data is displayed, 
there must be a way for the user to lirowse thrc^ugh the data and to specify which 
elements are visible and which are hidden. 

A familiar mechanism for doing this exists in the Finder, where small buttons indicate 
which cells have siibhierarchies and whether the snhhierarchy is visible. These 
mangular buttons have two stable states: ^ for closed (invisible) hierarchies and 
for open (visible) hierarchies. There are also three transient states: an intermediate 
button, is displayed brielly when the user dicks a triangidar button to change 
between the open and closed states; and the closed and open buttons are drawn filled 
when a mouse-down event is located on the button. 

To manage these buttons and tlie display of visible data, each list element needs a few 
flags and an intlentation varial)le. These are stored in the TwistDownRecord 
structure. 

The indentation variable — indentLevel -—^ specifies the hierarchic^al depth of an 
element and is tised to display suhlists so that the data for an element appears under 
its parent, hut indented to show its place in the hierarchy. 

The bits in the Hag field are used to record the recfird's state and to communicate 
between the application and the List Manager's list definition function (LDEF): 


/* These are the values that can appear in the flag word. */ 


fdefine 

kHasTwistDown 

0x0001 

/* 

This element has a sublist 

*/ 

#define 

kShowSublist 

0x0002 

/* 

Display the aubliet content 

*/ 

fdefine 

kOldShowSublist 

0x0004 

/* 

Saved kShowSublist state 

*/ 

tdefine 

k Selee t edE1eme nt 

0x0008 

/* 

Copy "selected" from list 

*/ 

fdefine 

kDrawB u11 o nFi11ed 

0x0010 

/* 

Signal "mouseDown" in button 

*/ 

fdefine 

kOnlyRedr awBut ton 

0x0020 

/* 

Signal "tracking mouse" 

*/ 

tdefine 

kDr awInt e rmediate 

0x0040 

/* 

Draw the animation polygon 

*/ 

tdefine 

kEraseButtonArea 

0x0080 

/* 

Need complete button redraw 



The flag field is defined as an unsigned short with explicitly defined bits rather 
than os a bitfield, which would hove mode the program slightly easier to read. 
However, the ANSI C stondard doesn't specify how the bits in a bitfield are arranged, 
and different compilers are free to choose their own organization of the bits. This 
means that if you write ports of your code using several compilers, or distribute 
modules in object form for others to use, you may cause o debugging nightmare. This 
is especially true if you use bitfields to construct data records that ore sent in network 
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messoges between d Efferent systems. The flag bits could have been defined as an 
enum, but this can also cause portability problems. Using explicit bit definitions will 
also make Et easier to convert your code to run on the Power Macintosh.* 


The first four flag bits have the following ineaning^i: 

• kHasTwistDown is set if the element should have a triangular 
button when it’s drawn. While you might assume that the 
existence of a non-null subElement pointer would he sufficient, 
the Finder illustrates a better design: it displays triangular buttons 
for all folders, even if there are no files in a folder. This 
immediately tells the user that the line on the display represents a 
folder, rather than a file. 

• kShowSublist is set if the siiblist should be displayed. This is 
normally contrrdled by die user clicking a triangular button, which 
changes the kShowSublist state. 

• kOldShowSublist is used to save the old kShowSublist setting in 
case you need to temporarily change the display hierarchy. This 
lets you undo a display state change or provide a Show' All 
Hierarchies command. It’s not used in the sample code. 

• kSelectedElement records the selection state of the list cell. It’s 
needed to properly retain die selection status of visible cells. 

The other flag bits are needed to handle mouse events. They^re set by the mouse¬ 
down event handler and the LDEF references them to control its actions: 

• kDrawRuttonFilled is set w'hen the user presses a button (the 
cursor is over a triangular button while the user has the mouse 
buttton held down). It causes the LDEF to fill the triangular 
button to indicate that the user is pressing it. 

• kOnlyRcdraw^Button is set to constrain the LDEF so that the 
entire display line doesn’t blink when the user presses a button. 

M the user moves the cursor in and out of the button, the drawing 
procedure must redraw the button to show wdiether the user is 
pressing the button. How^ever, there’s no need to redraw the 
actual data contents. This flag tells the LI>E^F to redraw only 

the button. 

• kDrawIntermediate is set when the user releases the mouse button 
within the button area: die !mtton state changes from closed ( >) to 
open (^ ) or vice versa. To indicate this change, the LDEF draws 
the button in an intermediate state (.i), delays for an instant, and 
then draw's die button in its new, stable state. 

• kEraseButtonArea is set to erase the button area before it’s drawn. 

If not set, the button is redrawn in its new fonn, but not erased; 
this eliminates unnecessary button flicker. 

The TwdstDowTi library uses the following four macros internally to access the flag 
word: 


idefine EetTDFlag(tdHandle, mask) 
idefine ClearTDFlag(tdHandle| mask) 
idefine InvertTDFlag(tdHandle, mask) 
idefine TestTDFlag(tdHandle, mask) 


((^*tdHandle).flag | = 
({**tdHandle).flag s= 
({**tdHandle),flag 
({(**tdHandle).flag & 


(mask)) 
-(mask)) 
(mask)) 
(mask)) 1= 


0 ) 
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CREATING THE LIST RECORD 

you first look at the List Manager-, it may appear to be the solution to all your 
display needs. Unfortunately, it has a number of characteristics that restrict its 
usefulness. It^s designed to store limited amounts of data, and performance slows 
appreciably as you increase the number of cells or the amount of data stored in the 
cells. Also, ifycjui’ list cells are not all the same size or your application needs fine 
control over scrolling, youdl probaldy find life simpler if you create your own 
function library. For example, both AlacApp and the THINK Class Librar)^ offer 
flexible libraries for displaying and managing structured data. However, the List 
Manager serves well for straightforw^ard lists of a small number of items — and with 
the addition of the triangular buttons it becomes a very useful tool. 

The TwisrDown subroutine library creates a one-column list with a vertical scroll bar. 
The code has only two unusual features: 

• NewTwistDownList stores a small amount of private information 
in a handle that’s stored in the userHandle field of the list record. 

This includes a pointer to a user-defined drawing function, the 
display font and font size, and a flag that signals whether clicking 
on cell data should highlight die cell contents. 

• It establishes a private LDEF that manages the visual display. 

Normally, the LDEF is stored in a resource. In the sample code, 
however, it’s linked into the application and a stub resource is 
created for the bene fit of the List Manager. This stub, a three- 
instruction procedure that die List Manager calls, jumps to die 
twist-down LDEF. i his is not necessary fiir this library — it could 
have been separately compiled — but is useful for debugging and 
for LDEF procedures that need to access application glohals. 

When you recompile ihis progrom to run on o Power Mocintosh as a "native"' 
application (rather than in 680x0-compatibility mode), you1f hove to redo this 
sequence slightly. The time to worry about conversion is now, before your customers 
are tapping you on the shoulder asking, "Not today? How obout next Tuesday?" 

There's more on converting for Power Macintosh ot the end of this orticle.* 


Note diat there are two separate drawing procedures: tlie twist-down LDEF manages 
the buttons and drawing for simple text displays, while die application progi'am can 
specify its own drawing hincrion to draw more cotnplex data. 

THE TWISTDOWNPRIVATERECORD 

The twist-down LDEF requires a small amount of global information to properly 
process die list. This is stored in a handle-based structure tlelined as showm in Listing4. 

Two Boolean variables in this record haven’t been described: canHiliteSelection and 
isLeftJustilyv The canHiliteSelection field controls whether the LDEF highlights 
selected cells. The isLefiJiisrify flag is set for left-to-right languages (such as English) 
and cleared for languages such as Arabic and Hebrew. This flag isn’t used in die code 
shown in this article, but the TwistDown library on the CD shows how an application 
might handle a right-to-left language. _ 

CREATING TRIANGULAR BUHON POLYGONS 

The triangular buttons are defined as QuickDraw polygons, rather dian as bitmaps, 
with the advantage that the hinction is independent of the list cell size anti script 
direction. This is useful for localization or for programs used by people who are 
visually impaired or have diminished motor skills: the program will display larger 
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y sting 4* Twis^ownPrivateRecord 
struct TwistDownPrivateRecord { 


Twis t Down Dr awP ro c 

drawProG? /* User- 

defined drawing function 

*/ 

PolyHandle 

openTriangle; 

/* 

The expanded button 


PolyHandle 

closedTrianglej 

/* 

The closed button 

*/ 

PolyHandle 

in te r me di at eTr i a ng 1 e ; 

/* 

Animation 

*/ 

short 

tabindent; 

/* 

Child indentation 


short 

fontSize; 

/* 

For TextSize 

*/ 

short 

fontHumber; 

/* 

For TextFont 

*/ 

Boolean 

canHxliteSelection; 

/* 

Highlight cell OK? 

*/ 

Boolean 

isLeftJustify; 

/* 

GetSystJust value 

*/ 

short 

triangleWidth; 

/# 

Button width 



} f 

typedef struct TwistDownPrivateRecord TwistDownPrivateRecord, 
*TwistDownPrivatePtr f * *Twis tDownPrivateHandle; 


buttons il the application or user chooses a large font. It also lets the program draw 
the closed and intermediate liuttons pointing in the proper direction for right-to-left 
script systems such as Arabic and Hebrew. Figure 3 illustrates an expanded view of 
die triangular buttons. As an example, the code in Listing 5 shows how you would 
create the polygons for a left-to-tight script. See the sample on the for more 
general code, wliich accounts for the writing direction of the script. 



Figure 3. The triangular buttons 

PUTTING DATA INTO THE LIST 

After creating the List xManager list, the application builds its hierarchical stmcnire 
(the linked list). List elements are created by the MakeTwistDownElement function. 
As described earlier in “Creating a List Element,” AlakeTwistDownElement obtains 
the necessary (handle) storage, initializes all flags, and stores the applicarion data in 
the list element. It also links the new element to the previous (elder sibling) element 
in the list. 

Normally, a twist-down list is built by a reem’sive function such as the one shov^m in 
Listing 6, MyBuildHierarchy. xMyBuildHierarchy calls a function named MyGetInfo 
diat stores a small amount of data into a sd'ucture called My Info Record. Neither of 
these is defined here: theyhe application specific, 

CREATING THE VISIBLE DISPLAY 

xAfter youVe built the data hierarchy, the next step is to determine which elements are 
visible initially and build the visible list. I’lie Create\%ibleList funcrion constructs a 
new visible display given the head of a hierarchical list and a List Manager handle. It 
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Listing 5. Creating triangular button polygons 
GetFontInfo(6info ); 

buttonSize = info.ascent? /* The button height */ 

buttonsise &= “1; /* Round down to an even nmnber */ 

halfSize = buttonSize / 2; /* For 45-degree triangles */ 

intermediateSize = (buttonSize * 3) / 4; 

(* * p riV at eHdi).openTria ngle = OpenP o1y()j 
MoveTo(0r halfsize); 

LineTo{buttonSize, halfSize); 

LineTo{halfSize, buttonSize); 

LineTo{0, halfSize); 

ClosePoly(); 

{**privateHdl)•closedTriangle = OpenPoly{); 

HoveTo(halfSizei 0); 

LineTo(buttonSizei halfSize); 

LinaTo(halfSizei buttonSize); 

LineTo(halfSizei 0) ; 

ClosePoly{); 

(**privateHdl) .intermediateTriangle = OpenPolyO; 

MoveTo(intermediateSize, 0); 

LineTo(intermediateSize, intermediateSize); 

LineTo(0, intermediateSiz e); 

LineTo[intermediateSize, 0); 
cloaePoly(); 



Listing 6. Building a twistdown list 


TwistDownHandle MyBuildHierarchy(ListHandle theList, short indentLevel) 


OSErr 

TwistDownHandle 
MyInfoRecord 
Boolean 
EventRecord 


status; 

previousElement, thisElement, firstEleinent; 

myInfoRecord; 

isHierarchy; 

currentEvent; 


firstElement - NULL; 
previousElement - NULL; 

/*** Other initialization here */ 

do { 

/*** Call EventAvail here to give time to background tasks, */ 

EventAvail[everyEvent, & currentEvent); 

status = MyGetInfo{&r[iyInfoRecord, aisHierarchy); 

if (status == noErr) 

status = HakeTwistDownElament(previousElement, indentLevel, 

sizeof(MyInfoRecord), (Ptr) ^myInfoRecord, athisElement); 
if (status == noErr) { 

/*** Remember the first element in this sibling sequence; */ 
/*** it's needed by our caller. */ 

if (firstElement NULL) 

firstElement = thisElement; 

(confinued on next page) 











Listing 6. Building a twist-down list (continued) 

/*** If this data begins a hierarchy, descend by calling this */ 
/*** function recursively. Store the first element of the new*/ 
/*** sublist in the subElement pointer, (flag & kHasTwistDown) */ 
/*** will be TRUE even if the child list is empty, */ 

if (isHierarchy) { 

SetTDFlag (thisE leitient, kHasTwistDown); 

(* *thisElement),subElemeat = 

HyBuildRierarchy(theList, indentLevel +1); 

} 

/*** Set sibling linkage for next element, */ 

previousElement = thisElement; 

} 

} while {status == noErr); 
r etur n (firs tElement); 

} 


stores the head in the first cell (cell [0, ()]) and calls BuildVIsibleList to store the 
\isible elements in the subsequent cells. 

BuildVisibleList is called in two situations: when the application first constructs the 
list and when the user changes the visual hierarchy by clicking a triangular burton. Ir 
calls CountVisibleElements to determine the number of ceils needed, adjusts the size 
of the list to the desired number, and calls a recursive function, SetElementsInList, to 
do the actual storage. SetElementsInList needs what is essentially a global counter to 
know which cell will receive the current list element. 

BuildVisibleList associates Ust cells with elements in the hierarchical list as foIlow^s: 

1, It copies the current selection status of each list cell from die List 
Manager cell to the associated TwistDownHandle element. 

2, It counts the number of elements that will be displayed and adds 
or removes rows from the List Manager list as needed. 

3, Finally, it stores references to the visible elements in the list ceils, 
updating the selection status as needed. 

The utility functions used in adding and removing elements from the List Manager 
list aren’t shown here hut may be examined in the sample library. BuildVisibleList 
uses several local, recursive functions to process the hierarchical list that all have a 
similar overall structure. For example, Count\^sibleElements (Listing 7) computes 
the number of list elements that should be displayed. 


HANDLING MOUSE EVENTS 

Now that we have a visible list, we’re ready to let the u.ser manipulate the hierarchy 
by clicking tiie triangular buttons. Wien the user presses the mouse button, the 
application decides w^hether the cursor is in one of its window's and whether this 
wdndow might just happen to have a ewist-down list. If so, the application calls 
DoTwistDownClick with the list handle, a pointer to an event record, and a pointer 
to a Cell structure that identifies the selected cell on exit. DolwistDownClick returns 
one of five action states, as shown in Table L 


DISPLAYING HIIRARCHICAl USTS 


67 






Listing 7. CounfVisEbleElements 

short CountVisibleElements|TwistDownHandle twistDownHandle) 

{ 

short result; 
result = 0; 

while (twistDownHaodle i= NULL) { 

++result; 

if (Te3tTDFlag(twistDownHandle, kShowSublist)) 

result += CountVisibleElements((**twistDownaandle).subElement); 

} 

return (result}; 


Table 1 

DoTw i stD ownC I i ck a cti o n sta te s 


Action State 

kTw I stDown Notl n Li 

kTwistDownNoCNck 

kiwi stDo wn B u Jto n CI j ck 

kTwistDownClick 

kTw i stDo wn Do u b leC I i ck 


Meaning 

The mousedown evenJ wos noJ in the lis)^ area. Your opplicatEon 
should handle this event. 

The user pressed the mouse button in o triangular button but 
released it outside the button. Your opplicotion should ignore 
this click. 

The mouse click was in the triangular button, DoTwlstDownClick 
has handled this, but your application may need to do further 
processing. 

The user clicked, once, on list doto. Your application may need 
to do further processing. 

The user double-clicked on list data. Your application may need 
to do further processing. 


The techniques described here for handling mouse events con be used to create 
lists whose cells contain other kinds of active elennents, such as buttons or checkboxes.* 

DoTwistDoMTiClick, together with the subroutines it calls, hides a fairly complex 
process consisting of the following steps; these steps are described further in the 
following sections and illustrated in the simplified version of DoTwistClick shown in 
Listing 8. 

L Check that the mouse-dowTi event is in the list area. 

2, Check that the user pressed a triangular button. 

3, Track the mouse while it’s held down. 

4, Take appropriate action when the mouse button is released. 

Did the user press in the list rectangle? 

Get the mouse location in local coordinates and the wdndow rectangle diat contains 
the list and its scroll bar. If the mouse location is not in the list, just remrn. 
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Did the user press a triangulor button? 

The user pressed in the list area^ is it in a button? The code sample on the CD has a 
test for left nr right alignment (so that yon can use the function with Arabic or 
Hebrew script systems) but that test is ignored here. The central algorithm 
determines the rectangle that encloses all the cell buttons. If the cursor is in tliat area, 
it then checks whether there is a cell under the cursor and, if so, whether this cell 
actually di>sp1ays a button. 

Track the mouse while it's in the button area* 

If we get past all that, we know that the aser pressed a mangular button. T he 
click-handler sets and clears flag hits that the LDEF references when redrawing 
the list cell. 'The LDEF starts by drawing the button in its active (filled) state. Note 
that each call to LDraw redraw's the list cell — but, as pointed out earlier, the 
kOnlyRed raw Button flag prevents the entire display line from blinking. 

'Lhe sequence beginning with ‘"if (StillDown())” in the code shows how you can track 
your own visual elements, such as icons, as if they were normal buttons. You can also 
use this technique to add checkboxes or other button-like objects to list cells. 

The U5er released the mouse button, 

UTien the user releases the mouse button in the triangular button area, the 
application changes the button state (for example, from t> to ^This is a tw^o-step 
process that briefly flashes an intermediate button (^) to give the user the illusion of 
change. While your application would certainly work without this subde touch, it 
wouldn’t look as good. Call the ExpandOrCollapseTwistDo\\mList function after 
flashing the intermediate button to redraw the button in its new state. Note that 
kEraseButtorLArea is set so that the intermediate button is drav^m properly. 


Listing 8. DoTwistDownClick 

TwistDownClickState DoTwistDownClick(ListHandle theList, 

const EventRecord *eventRecordPtr, 




Cell 

* s e1e cte dLis tCel1} 

Cell 

theCell; 

/* 

Current list cell 

*/ 

Rent 

hitRect; 

/* 

The button area in this cell 

*/ 

Boolean 

inHitRect; 

/* 

Cursor is in the button area 

*/ 

Boolean 

newInHitRect 

? 

Cursor moved into the button 

*/ 

short 

cellHeight; 

/* 

Height of a list cell 

*/ 

short 

visibleTop; 

/* 

Top pixel in the list area 

*/ 

Twi s t DovmHandl e 

twistDownHandle ; 

/* Current twist-down element*/ 

TwistDownPrivateHandle privateHandle ? 

/* Private data 

*/ 

Point 

mousePt } 

/* 

Where the mouse is located 

*/ 

TwistDownClickState 

result; 

/* 

Function result 

*/ 

long 

finalTicksj 

/* 

For the Delay function 

*/ 


/*** 1. Did the user press in the list rectangle? */ 

mousePt = eventRecordPtr->where? 

GlobalToLocal(fimousePt); /* House in local coordinates */ 

hitRect ^ (**theList}.rView; /* Here's the list area */ 

hitRect.right += kScrollBarWidth; /* Include the scroll bar, too */ 

(continued on next page) 
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Listing 8. DoTwist Down Click {continued} 

if (PtlnRect^mousePtp &hitRect) == FALSE) { 
result = kTwistDownKotInList; 
return (result); 


/*** 2. Did the user press a triangular button? */ 

privateHdl - (TwistDownPrivateHandle) (* *theList)♦userHandle j 
hitRect * right = (* * theList).rView.left + {* ^theList).indent•h 
+ (* *privateHdl).triangleWidth ; 
iuHitRect = FALSE; 
if (PtInRect(mousePt, ^hitRect)) { 

/*** The mouse is in the button area; is there a cell? */ 

cellHeight = {*'*^theList) *cellSize.v; 
theCell.h = 0; 

theCell.v = ((mousePt^v - (**theList)*rView,top) / cellHeight 
t (**theList)*visible*top; 

/#** This is a list cell that should have data. Get the twist- */ 
/*** down element handle* If there's no data, or no hierarchy, */ 
/*** the click will be ignored* */ 

twistDownHandle = GetTwistDownElementHandle(theList, theCell); 
if ((twistDownHandle 1- NULL) 

&& TestTDFlag(twistDownHandle, kHasTwistDown)) 
inHitRect ^ TRUE; 

if (inHitRect == FALSE) { 

/*** There's no button here, or the user didn't click it* Just */ 
/#** call the normal list click-handler and return its value* */ 
/*** This is needed to handle scroll bars correctly* */ 

if (LClick(mousePt, eventRecordPtr->modifiers, theList)) 
return (kTwistDownDoubleClick); 
else { 

return (kTwistDownClick); 

y 

} 

/***: 3 ^ Track the mouse while it's in the button area* */ 

S e tTD F1a g(twis t Down Handle, kDr awBu 11o nFi11ed | kOnlyRedr awBut ton); 
LDraw(theCell, theList); 

/*** Set hitRect to the triangular button dimensions* 
hitRect*top = (theCell*v - (**theList),visible*top) * cellHeight 
+ theList),rView.top; 

hitRect,bottom = hitRect,top + cellHeight; 

/*** Track the mouse while it's still down: if it moves into the */ 
/*** rectangle, redraw it filled; if it moves out, redraw it */ 

/*** unfilled* */ 

if (StillDownO) { 

while (WaitMouseUp()) { 

GetMouse{fimousePt); 

newInHitKect PtInRect [mousePt, & hitRect); 

[continued on next page) 
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Listing 8. DoTwistDownClick (continued) 

if (newInHitRect 1= inHitRect) { 

/*** yhe cursor moved into or out of the triangle. */ 

InvertTDFlag( twistDownHandle, kDra’wButtonFilled) ? 

LDraw(theCell, theList); 
inRitRect = newInHitHect; 

} 

} 


/*** 4. The user released the mouse button. */ 
if (inBitRect FALSE) { 

/*** The user canceled the operation by releasing the mouse */ 
/*** outside the triangular button area. drawButtonFilled will */ 
/*** normally be clear. It can be set, however, if the user */ 
/*** clicks so briefly that the StillDown() test above is */ 
/*** FALSE. */ 


if (TestTDFlagftwistDownHandle, kDrawButtonFilled)) { 

C1 ear TDF lag (t wi s t Do wnHart die), kDr awBut t on Filled); 
LDrav(theCell, theList); 

ClearTDFlag(twistDownHandle), kOnlyRedrawButton ); 
return {kTwistDownNoClick}; 

} 

SetTDFlag(twistDownHandle, (kDrawIntermediate | kEraseButtonArea)); 
LDraw(theCell, theList); 

Delay(kAnimationDelay, inalTicks ); 

ClearTDFlag(twistDownHandle, 

(kDrawIntermediate | kDrawButtonFilled | kEraseButtonArea)); 
ExpandOrCollapseTwistDownList(theList, theCel1); 

^selectedListCell = theCell? 

ClearTDFlag(twistDownHandle, kOnlyRedrawButton); 
return (kTwistDownButtonClick); 


EXPAND OR COLLAPSE THE HIERARCHY 

ExpandOrCoilnpseTwistDownList {Testing 9) is normally called directly by 
DoTwistDownClick, as shown in the preceding secrion. Ir can also be called direedy 
by the application. WTien called, it inverts the “expansion” state of the designated hst 
cell, redraw's the triangular button, and calls BuildVisibleLisr (described earlier in 
“Creating the Visible Display”) to revise die visible hierarchy. Note that 
BuildVisibleList will modify the display starting w'ich the current cell: the cells above 
will not change and thus need not be modified or redrawn, 

DRAWING THE LIST CELL 

WTien the contents of a list cell change or the display requires updating, the List 
Manager calls the TwistDownLDEF function. This function drawls the button in its 
current state and either draws the list cell (for simple text cells) or calls a user-defined 
drawing function to draw more complex cells. The code is generally straightforw^ard 
(again, ignoring right or left considerations). Basically, it examines the state of the 
kOnlyRedraw Button flag and proceeds as follows: 
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• If the flag is set, '^shrink” the display rectangle so that only the 
burton is redrawn. Choose the correct triangular polygon and 
draw it in its proper state. 

• If the flag is clear, draw the cell data and the mangular polygon. 

Let’s look more closely at the TwistDot^mLDEF drawing code (Listing 10): 

L First we determine what to draw. To begin drawing the list, we 
first need the cell content. This is the handle that contains the list 
element. We also check chat userHandle has been set up correctly. 
Note that we don’t use the List Manager’s LFind function because 
the data might not be aligned in the list cell storage, (Actually, the 
data is aligned, because only handles are stored in the cells, but it 
doesn’t hurt to be suspicious.) If the handle contains a list element, 
the values of die flags determine what to draw. 

2. Next, we call DrawTriangle to draw the triangular button. The 
value of theFlag determines the button state and its location, 

3. Finally, after checking to be sure kOnlyRedrawButton is not set 
and that we have the data, TWistDownLDFF redraws the cell data 
with the proper indentations. Here’s where the code allows you to 
specify a user-defined drawing function. 


Listing 9. ExpondOrCollapseTwEstDownList 

twistDownHandle - GetTwistDownElementHandle(theList, theCell); 
if ((twistDownHandle I= NULL) 
kSi TestTDFlag(twistDownHandle, kHasTwistDown)) { 

InvertTDFlag(twistDownHandle, kSHowSublist)? 

/*** Redraw the triangQlar button in its new state. */ 

ClearTDFlag(twistDownHandle, kDrawButtonFilled); 

SetTDFlag(twistDownHandle, (kOnlyRedrawButton | kEraseButtonArea)); 
LDraw(theCell, theList); 

Cle arTDF1ag(twis tDownfi an d1e, (kOn1yRedr awBu11 on | kEr a s eBut tonAre a))? 
/*** If some other part of the list will change, rebuild the List */ 
/*** Manager cells and redraw the list, */ 

if ((**twistDownHandle).subElement HULL] 

BuildVisibleList[theList, theCell.v ); 

} 


Listing 10 - TwisJDownLDEF drawing code 


pascal void TwistDownLDEFf 


short 

Boolean 

Rect 

Cell 

short 

short 

ListRandle 

) 


listMessage, 

listSelect, 

*listRect, 

listCell, 

listDataOffset, 

listDataLen, 

theList 


/* Unused 
/* Unused 


*/ 

*/ 


(continued on next page) 
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Listing 10, TwisfDownLDEF drawing code (continued) 


short 

indent; 

/* 

Cell data indentation 

*/ 

TwistDownHandle 

twistDownHandle; 

/* 

The cell data 

*/ 

TwistDownPtr 

twistDownPtr; 

/* 

Cell data (locked handle) 

*/ 

short 

cellSize; 

/* 

sizeof(TwistDownHandle) 

*/ 

PolyHandle 

polyHandle; 

/* 

Button polygon 

*/ 

Point 

polyPoint; 

/* 

Where to draw the button 

*/ 

Rect 

viewRect; 

/* 

Actual cell drawing area 

*/ 

signed char 

6lementLockState; 

/* 

twistDownHandle lock state 

*/ 


#define TestFlag{flagBit) {(theFlag & (flagBit)) 0) 

, * * /*** Other LDEF processing isn't shown. */ 

/*** 1. Detemine what to draw. */ 

cellSize = sizeof twistDownHandle? 

LGetCell(&twistDownHandle, scellSize, listCellr theList); 
if {{cellSize — sizeof twistDownHandleJ && twistDownHandle i- NULL) { 


/*** There is a list element. (This if statement extends all */ 
/:*** the way to the end of the sequence.) Lock the element in */ 
/*** inemory and look at the flag values. Set viewReot to the */ 
/*** part of the List Manager cell that will be drawn. */ 


elementLockstate “ BGetState({Handle) twistDownHandle ); 

HLock{(Handle) twistDownHandle); 
twistDownPtr = (^twistDownHandle)? 

privateHdl (TwistDownPrivateHandle) (* ^theList).userHandle ; 

viewRect ^ *listRect; 
theFlag = {*twistDownPtr).flag; 
if (TestFlag(kOnlyRedrawButton)| { 

/*** Shrink the display area when only the button is redrawn.*/ 
viewRect.right = viewRect.left + {**theList).indent.h 
t (* *privateHdl),triangleWidth ; 

} 

if (TestFlag(kOnlyRedrawButton) == FALSE 
II TestFlag(kEraseButtonArea)) 

EraseRect(&viewRect); 

/*** 2, Draw the triangular button. */ 

if (TestFlag(kHasTwistDown)) { 

polyPoint.v = listRect->top + 1; 

polyPoint.h = llstRect->left + {**theList).indent.h 
+ kTriangleOutsideGap? 
if (TestFlag[kDrawIntermediate)) 

polyHandle = (**privateHdl).intermediateTriangle; 
else if (TestFlag(kShowSublist)) 

polyHandle = {**privateHdl).openTriangle; 
else 

polyHandle = (* *privateHdl).closedTriangle; 

DrawTriangle(polyHandle^ polyPoint, theFlag £ kDrawButtonFilied); 

} 

(continued on next page) 
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Listing 10* TwistDownLDEF drawing code (continued) 

/*** 3. Draw the cell data. */ 

if {TestFlag (kOnlyRedrawButton) == FM^SB 
(*twistDownPtr) .dataLength > 0) { 

/*** Indent the text to show the depth of the hierarchy. Then */ 
/*** build a display rectangle for the cell text and set the */ 
/*** pen to the leftmost position of the text. */ 

indent = (**theList)* indent.h + {**privateHdl).triangleWidth 

-t- ((**privateHdl) .tablndent * (*twistDownPtr). indentLevel ); 
viewRect = ^listEect; 
viewRect.left t= indent? 

TextFont((**privateHdl).fontNumber); 

TextSize{(**privateHdl).fontsize); 

/*** If the user didn't provide a drawing procedure, draw a */ 
/*** text string. Otherwise, call the user's procedure. */ 

if {(**privateHdi).drawProc =- NULL) { 

MoveTo(viewRect.left, viewRect.top t (**theList).indent.v); 

DrawText({* twistDownPtr).data, 0, (*twistDownPtr).dataLength); 

} 

else { 

(*(**privateHdl) .drawProc) ( /* Call user's drawing function 



theList, 

/* The list handle 

*/ 


(const Ptr) 

(*twistDownPtr).data, /* Data to 

draw 

*/ 


(*twistDownPtr).dataLength, /* Size of 

the data 


} 

> 

fiviewRect)? 

/+ Where to draw it 

*/ 


/* If we're drawing cell 

data 

*/ 

HSetState((Handle) twistDownHandle, elementLockState)? 





If we have cell data 


*/ 


THE DRAWTRIANGLE FUNCTION 

If you look closely at the trian^ilar Inittons on a color or griiyscnle display you'll 
notice rhnt the button is filled with a grayish background color. fFhe Finder uses the 
color the user assigned to the file, wHiile we use a light gray color.) The DrawTriangle 
function called by IwistDownLDEF takes three parameters: the polygon, where it's 
to he drawn, and a Boolean that specifies w'hether the user is currently pressing the 
triangular button. DrawTriangle uses the DeviceLoop procedure, DrawThisTriangle, 
which calls the actual drawing function for each type of dc\icc so that drawing can he 
optimized for different screen depths. (See Listing 1L) 

The DeviceLoop procedure is described in "DeviceLoop Meets the InterFace 

Designer/' develop Issue 1 3, and in Inside Macintosh Volume Vi.* 


THE SAMPLE PROGRAM 

The sample program illustrates how you can use twist-down lists to display a 
directory of all files on a volume. It’s a very simple program and you would be w'ell 
advised not to use it on a huge disk wath many folders and files, because diere's no 
protectitm against storage overflows 
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The sample program compiles and runs in five environments: THINK C 6.0, 
Metrow^erks DRl, and MPW 3.2 for the 680x0-based Macintosh; and, for the Power 






Listing 1 1 , DrawTriangle and DrawThisTriangle 


typedef struct Triangleinfo { 
PolyHandle polyHandle; 

Point polyPoint; 

} Triangleinfo, *TriangleInfoPtr; 


/* Passed to DrawThisTriangle 
/* The polygon to draw 
/* Where to draw it 


*/ 

*/ 

*/ 


static void DrawTriangle(PolyHandle polyHandle, 


} 

Triangleinfo 

RgnHandle 

long 


Point 

Boolean 


triangleinfo; 
drawingRgn; 
savedA5; 


polyPoint, 
isSelected 


/*** Refresh AS so that we can use the current QuickDraw globals, 
savedAS = SetCurrentAS(); 

triangleinfo.polyHandle ^ polyHandle; /* Save our drawing 
triangleinfo.polyPoint = polyPoint; /* parameters* 

/*** Position the polygon properly on the display* 

Of fsetPoly(polyHandle, polyPoint.h, polyPoint.v); 
if (isSelected) 

FilIPoly(polyH andle, &qd.black); 
else { 

/ika* Get drawing region and call DeviceLoop to do the work. 
drawingRgn = HewRgn(); 

OpenRgn(J; 

FramePoly(polyHandle); 

CloseRgnIdrawingRgn); 

DeviceLoop( 

drawingRgn, /* Region to draw into 

(DeviceLoopDrawingProcPtr) DrawThisTriangle, 

(long) Strianglelnfo, /* Drawing parameters 


*/ 

*/ 

V 

*/ 


*/ 


*/ 


*/ 


/* DeviceLoop flags (ignored)*/ 


DisposeRgn(drawingRgn); 


} 

/*** Frame the button in black and move the polygon back to its 
/*** default [0,0] position. 

FramePoly(polyHandle); 

OffsetPoly(polyHandle, -polyPoint.h, -polyPoint.v); 

SetAS(savedAS); 


*/ 

*/ 


c pascal void DrawThisTriangle( 

/* Called by DeviceLoop 


short 

depth. 

/* Screen pixel depth 

*/ 

short 

deviceFlags, 

/* Device info (ignored) 

*/ 

GDHandle 

targetDevice, 

/* The display (ignored) 

*/ 

TriangleInfoPtr 

t riangleinf oPtr 

/* The data to be drawn 

*/ 



fconh'nued on next page) 
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Listing 11 ■ DrawTnangle and OrawThlsTnangle (contfnuedj 


RGBColor 

RGBColor 

RGBColor 

short 

Rect 


foreColor; 

saveForeColor; 

backColor; 

i; 

polyRect; 


polyRect = [* *(*triangleInfoPtr).polyHandle).polyBBox; 

LocalToGlobal(& ((Point *) &polyRect)[0 J); 

LocalToGlobal(& ({Point *) &polyRect)[1]); 
if (depth > 1) { 

/*** Drawing in color or grays: fill the triangle with a very */ 
/*** light gray, +/ 

GetForeColor(aforeColor); 
saveForeColor = foreColor; 

GetBackColor(abackColor); 

/*** This loop sets foreColor to a very light gray. */ 

for (i = 0; i < 8; i4+) { 

if {GetGraY{GetGDevice(), abackColor, &foreColor) == FALSE) 
break; 

> 

RGBForeColor{afor 0 Color); 

FiliPoly({*trianglelnfoPtr).polyHandle, &qd,black); 

RGBForeColorjasaveForeColor); 

} 

else { 

/*** Monochromet erase the interior of the polygon, */ 

Erase?oly((*triangleInfoPtr),polyHandle); 

} 

} 


Macintosh, Metrowerks DR] and the MP\Y provided in die Macintosh on RISC 
Software Developer’s Kit, Cotiverting the code for Power Macintosh took about one 
day (it was niy lab exercise when I took the .\pple Developer University “Pow^erPC 
BootCamp” course), 'Fo learn more about what I did to accomplish this conversion, 
see ‘‘Converting for Pow'er Macintosh, 

When you start up the sample program, it begins enumerating the disk; you can click 
to stop it at any time. The hierarchical list is built using the algorithm illustrated by 
the MyBuildHierarchy function, described in the section “Putting Data Into the List.” 

TWISTED LISTERS 

So, what’s this method of displaying data good lor r If you have data diat’s 
hierarchical, coherent, line-oriented, and not too large, you’ll find that the twdst- 
down list functions are both useful and easy to incorporate into your applications, 

• Hierarchical, If the data doesn^t separate into a strict hierarchy, the 
presence of triangular buttons will only confuse your users: they’re 
expecting your application to operate like the Finder, Mso, if the 
hierarchy is verv*^ limited (a single topic witli a block cjf text), you’ll 
probably find some other solution easier to use. 
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CONVERTING FOR POWER MACINTOSH 


Here's a simplified checklist of the kinds of things you'll 
need to do to convert code for the Power Macintosh, 
based on what I did to convert my program (see the 
sample code on the CD, especially TwistDownUst.c). I 
borrowed heavily from the document "Moving Your 
Source to PowerPC" on the Macintosh on RISC Software 
Developer's Kit CD. 

• Convert to standard C using the most restrictive 
environment so that the application runs correctly in 
THINK C and MPW with no compiler or linker errors 
or warnings. In THfNK C, for example, you would 
enable the Check Pointer Types and Require Prototypes 
options and remove the MacHeaders option. In all 
coses, you should add prototypes and explicit function 
return types and fix potential trig rap h problems. 

• Replace all instonces of int and unsigned by explicit 
shart and long declarations. Be very careful about 
structure definitions that are shared among code 
modules (or written to Files or resources), as the Power 
Macintosh aligns structures differently from the 680x0- 
based Macintosh: you may need to add #pragma 
statements to override the compiler, 

• Create a makefile for the MPW development system. 
Try to build "fat binaries" that will run native on both 
the 680x0-based Macintosh and Power Macintosh. 

• If at all possible, convert to the universal interfaces 
provided in the Software Developer's Kit (ond on this 
issue's CD). In particular, ProcPtr references must be 
converted to UniversolProcPtr. Also, oil low-memory 
references must be replaced by the access functions 
provided as part of the universal interfoces. 

• Isolate system and compiler dependencies by using 
#!fdef statements. For MPW-based compilers, odd 
-d MPW^I to your makefiles. This lets you add 
compiler- and system-dependent #pragmas ond code 
sequences without encountering compiler warnings. 


fifdef THINK^C 

/* 

THIM C 


fifdef powerc 

/* 

Power Macintosh 


fifdef MPW 

/* 

MPW: see above 

*/ 

fifdef applec 

/* 

Apple compilers 

*/ 


* Remove or isolate all assembly language and inline 
statements. You can probably eliminate all assembly 
language from your Power Macintosh applications. 

* Power Macintosh will not support a number of obsolete 
system traps; when you convert your program, you 
may need to rewrite small sections of your code. Of 


course, you should check new code on both the 
680x0-based Mocintosh and Power Macintosh. 

• Applications must explicitly allocate space for the 
QuickDraw globals. Add the following to your 
application's main program file: 

fifdef powerc 

QDGlobalsqd; 

#endif 

• Avoid storing application-specific dota in your 
application's data fork: the Power Macintosh stores its 
code there, [You can reserve a fixed amount of space 
at the beginning of the data fork, if necessory,) 

• Add o 'cfrg' (code fragment) resource to your 
application's resource fork. This tells the Process 
Manager that you've built a Power Macintosh native 
application. 

fifdef _powerc 

linclude "CodeFragmentTypes.r" 
resource 'cfrg' (0) { 

f 

kPowerPC, 
kFullLib, 

kNoVersionNuM, kNoVersionNum, 

0 , 0 , 

kIsApp, kOnDiskFlat, 
kSeroOffset, kWhaleFork, 

"MyFir s tPower PCApp" 

} 

}; 

tendif 

• Make good use of the compatibility built into the 
Power Mocintosh: your opplicotion should run native 
on Power Macintosh and still run correctly on a 680x0- 
based machine. The user shouldn't notice any 
difference, 

• In most cases, native PowerMacintosh applications 
will be about the same size as their 680x0 
counterparts. Of course, if you use the compatible "fat 
binary" capability, the application file size will 
increase. 

The above list isn't complete by any meons, but, together 
with the sample code, it should get you started. Also, 
there are several Developer University courses available 
to help bring you up to speed quickly. 
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• Coherent. Your users expect consistency bemeen the parent ‘‘tide” 
and child “content” data- Try another technique if clicking a 
triangular button does something other than reveal a lower-level 
hierarchy. For example, the JAIP statistical package uses standard 
Macintosh buttons to expand a hierarchy. Clicking a button may 
reveal a table of data or a graphical element. QMP hierarchies are 
also quite shallow.) 

• Line-oriented. i^Vgain, the user is expecting Finder-iike behavior. If 
the data is not line-oriented, you’ll discover that coaxing the List 
Manager to deal with your data isn’t worth the considerable effort 
it takes. In particular, avoid varying the height of each line as this 
makes the triangular buttons look weird (some small, some large) 
unless you normalize their size. 

• Not too large. This is a restriction of the List Manager. Because of 
the way it stores data, there’s an absolute limit of 32,767 cells in a 
list, but it becomes v^ry slow and clumsy with more than a few 
hundred cells. 

I wrote the TwistDo%\m librabecause I wanted to display an AOCE catalog 
specification that can contain many internal components of varying size and 
complexity It offered a friendly interface into a structure that is convoluted, warped, 
and — indeed ' — Cv^asted. 
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TAO JONES 


Dear Taoy 

SmmQ7it: at ivtirk k stealing all rny pens. I knm) it doesn'^t 
sound like a big deal., hut ifs getting to the point where Fm 
going tbroMgh doze?ts a week. Even mo?T finstrating is that 
Fm cenain ifs happen mg during normal bminess horns, not 
at night. 

I just know the hitetmal Revenue Se?^^^ isn V going to 
believe a huge deductmi for office supplies at the end oj^ the 
year. What can / do? 

Pound Wise But Pen Poolish 
Dear Pound, 

You are in one of those unique positions where you can 
nt)t only solve the mystery of the missing^ pens, but also 
spruce your office up a hit. 

The first thing you need to do is cover ycuir walls with 
blacklight posters. As a minimum you should get a 
tiger, a Jimi Hendrix, and a flaming dirigihle. Wiat’s 
really great is that although interior design has taken 
huge leaps fomard since the 60s, blacklight art has 
remained remarkably the same. Any investment you 
make now is sure to be preserved for years. 

Once youVe got the posters, you naturally must have a 
biackhght to properly show them off. I would 
recommend the most powerful one you can get, but 
you should stay away from the strobes — although rare, 
there are some people who experience seizm'es from 
strobe light. 


At this p{)int the trap is set. Now all you need to do is 
dust your pens with ultraviolet powder (available from 
any burglar alarm shop). Alake sure that you leave the 
light off for the first day or two. Then turn it back on 
and watch tlie people who come back and forth from 
your office. The one with the glowing yellow hands is 
your best suspect. 

Note that if youfre going to spend much time working 
under these lamps, you should get yourself a pair of 
UV goggles. It^s not a bad idea to have a pair anywayj 
diey make a great fashion accessory to spice up any 
wardrobe. 

If things ever get a bit dull around the office, you can 
always set tip your own security desk. Imagine the thrill 
youil get saying things like “Excuse me, miss, you1l 
need to be stamped in order to reenter the building.” 
Putting up a sign that reads “No bottles, cans, knives, 
or tape recorders” will just add to die ambiance. 

Dear TaOy 

Lately Pve been pondering a real big question that I'm not 
making any headivay with: what, exactly, is it that people 
are ttying to accomplish? Sure, all these software companies 
are trying to change the world, make profits, and all of that, 
hut why? 

Puzzled 
Dear Puzzled, 

Yoiifre asking the question that has plagued people 
from time immemorial. Ids been phrased lots of 
different ways, usually by big people thinking big 
thoughts and wearing strange clothes, but the crux is 
always the same: just what is the deal? 

Different reUgions and philosopliies will give you 
different answers. Buddhists will tell you about 
enlightenment, Christians will expound on heaven, 
existentialists will ask “WTiy do you even care?” and a 
ten-year-old kid will point to a candy store. 
Unfortunately, all of these solutions look too far 
forward into die future, are too imbued widi concepts 
of the human spirit, and still are not answering the 
basic question as it concerns computing. 


TAO JONES potdhts way through college by volunteering as o 
sub|ect for psychology experiments. He become obsessed with 
trying to Figure out whot the experiments he was participating in 
were trying to determine and then defeating them. One doy he 
was told to go to the testing room down the hoi I and on the right. 


He went down the hall ond entered o room thot was completely 
dork. Figuring it was an experiment in sensory deprivation, he 
went in and sat down. Two days later, he emerged, neorly dead 
from dehydration. It was then that he discovered he'd gone down 
the hall and turned /efr only to end up in the janitor's doset." 
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I know the answer, but as part of the fraternity of 
philosophers, advice colunmists, and mapcians, Fm not 
supposed to release our secrets. However, Fve never 
been comfortable with being a part of the “in” crowd, 
so Fll tell you the answer: it’s Pac-xMan, 

From Day 1 people have wanted to be entertained, but 
for millennia this need was never truly fultilled. Then 
in die 1980s Pac-Alan came along and there was a brief 
period of bliss. Money could actually buy happiness — 
assuming you had at least a quarter and a Pac-Man 
machine nearby. 

Of course, a person can take only so much of any given 
kind of happiness, especially one that goes “wokka, 
wokka, wokka, GOINK!” People became burned out, 
and the search has liecn on ever since. That’s right; this 
S200 billion-a-year indnstry^, and all those government 
think tanks, are actually doing nothing more than 
searching for the next Pac-Man, Most experts agree 
diat the next big breakthrough will be in a driving 
game of some type, which explains why youVe been 
hearing so much about the digital highway lately. 

Dear Tao, 

Believe it or not, I Mtually like ivearing a wt to the office. 
I've tried the standard jeans and T-sbh't outfft, Imt I ftist 
don't feel comfortable in them. My problefn is that when I do 
dt^ess up, my colleagues conthmaHy criticize ?ne for it. What 
can 1 do^ 

Pi??stJiped in Pefnnylvartia 
Dear Pinstriped, 

Unfortunately, youfre in a very^ difficult situation that 
probably isn’t “curable.” The ailment was discovered in 
the 1950s and is most commonly referred to today as 
the “Liberace Syndrome,” The studies of the human 


genome seem to indicate that there’s some sort of 
defect in the appearance gene that will make affected 
individuals v^ant to start dressing flashier and flashier. 
It’s not clear what causes it, although chronic exposure 
to jcwelr)^, candelabra, or Las Vegas clearly will make 
the condition worse. You’ll also find that your 
condition will become more severe with age. 

The disease starts very mild. At first youll shun 
sneakers. Then you’ll start thinking that cotton has too 
rough of a feel. As things progress to the final and most 
outrageous stages, you’ll find yourself wanting to wear 
sequined capes and featlier boas. Thousands of people 
have been afflicted by the Liberace Syndrome: Little 
Richard, FJvis Presley, Elton John, Madonna, James 
Brown, and Rip Taylor, to name a few. 

So it’s bad news and good news about your affliction. 
The good news is that it’s possible to live a full, 
relatively happy life, d'be bad news is that you’ll never 
be able to do so in the computer industry. My 
recommendation is to start singing every morning in 
the shower, find an agent, and figure out which colors 
best match your hair and complexion. 


RECOMMENDED READING AND 
LISTENING 

• T/re Official Scrabble Flayers Dictionary by 
Selchow & Righter. Great words From oo to 
zyzzyvo. 

• Pop Art Book of 30 Postcards by Magna Books. 
High time to send your friend o Lichtenstein. 

• SebooFs Out by Alice Cooper (Warner Bros. 
Records). Try to find o used copy of the LP, which 
includes paper panties that were banned as a 
'Tire hazard. 


Too Index: A person's belief in the truth of a particular argument 
is inversely proportional to their emotiona! fury in delivering it.* 


You con determine the future of Too Jones. Simply put, this 
may be Tao's last column. If he receives no more questions, we will 
put him in a [ob better suited to his skills: repairing Lisas and Apple 
Ills. Will Too be saved? Only if enough of you AppleLink DEVELOP 
with a question on office survival* 
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The Right Way to Implement 
Preferences Files 


Many Macintosh applications use preferences files to keep track of 
user preferences. This article describes the characteristics of a well 
implemented preferences file and introduces a library that manages 
this work for you. 



GARY WOODCOCK 


Preferences files have become a standard feature of most Macintosh applications. 
With these files being so commonplace, iPs timely to investigate how to implement 
them properly- We'll first take a look at what constitutes a well implemented 
preferences file; then we'll inspect a library API tliat provides a simple means of 
creating and interacting with preferences files. On this issue's C^D you'll find source 
code for a standard preferences library and a test application that illustrates how^ to 
use the lihraiy. This library is wTitten with version 6.0,1 of Symantec's THINK C for 
Macintosh using the universal interface files (%vhich can also be found on the CD). 

Before w^e begin, let's take a look at when and when not to create a preferences file. 

A preferences file needs to he created only when the user has altered the default 
configuration of the application. Upon being launched for the first time, many 
applications auromatically search for a preferences file and, if it isn't found, 
immediately create one. But why? Has the user changed anything? Nope. The user 
probably hasn't even had an opportunity to pull down an application menu at this 
point. So why do we need to create a preferences fife? We don't, and we shouldn't. 


But given those situations in w'hich your application shoukl create a preferences file, 
read on to learn how to do it the right way. 


WHAT MAKES A WELL IMPLEMENTED PREFERENCES FILE 

The tw^o Finder info windows shown in Figure 1 illustrate a poorly implemented and 
a well implemented preferences file. We can categorize the visible differences in 
Figure 1 by file type, document kind, Finder icon, and version information, as 
explained in the following sections. Note that the concepts presented here apply to 
implementing any kind of document file, not just preferences files. 


FILE TYPE 

Like any other file created by your application, yom’ preferences file should have a 
unique file type, w^liich is specified in a fife reference (TREF') resource in the 


GARY WOODCOCK, fonnerly of Apple but 
now at 3 DO, is currently ossimilaling experiences 
accrued during his onnual pilgrimage lo the South 
by Southwest Music Conference in Austin, Texas. 
For those reoders who Find stimulation in 
spending Four days and nights attending live 


performances by □ diverse assortment of 
interesting, boisterous, and relatively unknown 
bonds playing in a variety of beer-drenched pubs, 
in the company of equally interesting, boisterous, 
and beer-drenched people, a better venue Gary 
cannot recommend.* 
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S LazyRpp Prefs Info ?-■■■. 


ifli 

MegalllhizzyRpp Preferertc 


Lazy App Prefs 



“ MegaVhizzy App Preferences 
(for Mega'¥/^hizzy App 1.0) 


Kind: docym^nt 

Size-: 7K on disk (394 bytes used) 

Vhere : Mojo: System Folder : Preferences; 


Created: Sun, Oct 17, 1993,7:12 PM 
Modified: Sun, Oct 17, 1993,9:13 PM 
Version: n/a 

Comments: 


A poorly implemented preferences file. It has 
an undefined icon, it doesn't indicate vfhat 
application created it or vhat kind of document 
it is, and it has no version information. 


n Looked 


I I Stationerij pad 


Kind: Preferences document 
Size: 7K on disk (750 bytes used) 

Vhere : Mojo: System Folder : Preferences: 


Created: Sun, Oct 17, 1993, 7:12 PM 
Modified: Sun, Oct 17, 1993,9:10 PM 
Version: 1 .0 (US), © Apple Computer, Inc. 
1993“94 

Comments: 


A well implemented preferences file. It has an 
ioon, it indicates what application created it and 
what kind of document it is, and it has version 
information. 


n Looked 


I I Stationery pad 


Poorly Emplemented preferences file 


Well imptemenfed preferences file 


Figure 1* Info windows for example preferences files 


application. The file type of the preferences file should he associated with the 
application sigiiature so that the Finder can display which applicatitin created the file 
when its infi) window is showni. This association is matle in your application’s bundle 
{’BNDL’) resource, w^hich includes the application signature, the file reference 
resources, and the application and document file icons, d'he info window for the 
pt)orly implemented preferences file shown in Figure 1 doesn’t display any 
information about wdtich application created the file because the file type isn’t 
associated with an applicati<)n signature. 

Incidentally, you should not use 'preF as the file type for your preferences file; this file 
vypt is reserv'ed for the Finder Preferences file (as you’d find oui if you tried to 
register this file type with Apple’s Developer Support Center — you were going to do 
that for the file type of your preferences file, right?), IF you w ere to give your 
preferences file this file t}^>e, you’d norice that when the user turns on Balloon Help, 
the Balloon Help for your preferences file is actually the Balloon Help for the Finder 
Preferences fife. I'll go out on a limb here and assume that we can all agree this is 
confusing for users, and should therefore be avoided. 

DOCUMENT KIND 

A file’s Finder info window also indicates the kind of document the file is. In many 
cases, this field reads either 'kioenment” or something like ^'MegaUliizzyApp 
document.” But with the introduction of the Translation Manager (first made 
available with Macintosh Easy Open), a new resource type has been defined that your 
application can use to more accurately describe its files, including its preferences file. 
This resource is called the 'kind' resource, and its Rez definition is as follows: 

type 'kind' { 

literal longintj /* App signature 

integer; /* Region code of kind string localizations */ 

integer = 0; 

integer = $$Count0f(kindArray); /* Array size */ 
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/* File type */ 

/* Custom kind strings */ 


wide array kindArray { 
literal longint; 
pstring? 
align word? 

}; 

}; 


All example 'kind' resource might look like this: 

resource 'kind' (128) { 

'TSTR^, 

0 , 

{ 

’TEXT', "MegaWhiazyApp text document" 

} 

}; 


In this example, assuming the Translation Manager is present, a file with creator 
'TSTR’ and file type 'TEXT' will display the string ^^MegaWTiizzyApp text 
document” in the document kind field of its info window* 

FINDER ICON 

As suggested in Macintosh Himmn Intefface Guidelines^ die best icon for preferences 
files is either the standard preferences file icon or an icon that incorporates some 
elements of the standard preferences fife icon (see Figure 2). It’s not taboo to use a 
unique preferences file icon, but diis may make it difficult for users to recognize the 
file as a preferences file* 



Standard Icon Movie Recorder ResEdit 


Figure 2, Example preferences file icons 


As noted above, you provide a Finder icon for your preferences file the same way that 
you provide Finder icons for your other document files — through a bundle resource 
in your application. 

VERSION INFORMATION 

A file’s vers' (version) resources determine what version information is displayed in 
the Finder info window. There are normally two vers' resources for a file — 'vers’ 
IDs 1 and 2 — and each contains the following: 

• A nuineric code representing the version* This code consists of a 
major revision number^ a minor revision number, an optional bug 
fix revisiem number, a stage code (development, alpha, beta, or 
final), and a revision level (for non-final stages). 

• A region code, which indicates the localized version of system 
software appropriate tor use with the file* 

• A short version string identifying the version number. 

• A long version string consisting of the file version number and 
company copyright in Vers' ID I, and the product version number 
and name in Vers' ID 2. 
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Far more information about these resources and how they affect what’s displayed in 
the Finder info window, see pages 7-31 to 7-32 of Madntosh: Macintosh Iholhox 
Esse7itiah\ For the structs corresponding to the Vers' resource, check out the Files.h 
header file. 

Providing version information in your preferences files does more than just make the 
Finder info window look pretty. You can use this infonnadoo to identify the format of 
the data contained in a preferences file. This is useful in determining how to translate 
preferences data created by an older version of an application into the preferences 
format for the current version of the application. 

CAN USERS OPEN PREFERENCES FILES? 

Users have a penchant for running raiiipant through their hard disks, looking for 
interesting files to open, particularly if the files w eren’t explicitly created by them. 
Files kept in the System Folder are no exception to this experimentation, so it should 
come as no surprise to you that your application should be prepared to correctly 
handle the case where its preferences file has been double-clicked. 

There are several interesting possiljle behaviors that a preferences file might exhibit 
under these circumstances. One alternative is that the application die preferences file 
belongs to could launch, con figuring itself with the data contained in the file. A 
variation of this behavior would be to display the application’s preferences dialog after 
launching, if such a dialog w'ere supported, A third behavior is that when a user 
double-clicks a preferences file, its application isn’t launched, but instead a dialog is 
displayed describing what the llle is, where it belongs, and w'hy it can't be opened. 

Ibday, the only preferences file l)ehavior approved and documented by Apple is the 
last one. The Human Interface Design Center of Apple’s system sedWare group has 
this to say about preferences files: 

• Preferences flies shoiihl not be treated as if they were documents 
created by the user. Launching an application and optionally 
opening a preferences dialog support the misconception that they 
are like documents, 

• Not all applications have preferences dialogs. Launching an 
application that doesn’t have a preferences dialog when its 
preferences file is double-clicked is confusing, because there’s 
nothing specific to show' the user that represents the information 
stored in the file, 

• The current thinking is that a user doesn’t open the System 
Folder, sec a preferences file for Mac Write (for example), and 
W'Onder what the preferences for Mac Write are set to; he’s more 
likely to see the file and wonder w^hat it’s used for. In this case, an 
informative dialog that’s displayed when the user attempts to open 
the preferences file better satisfies the user’s intent. 

• Ideally, users shouldn’t really even have to know^ about preferences 
files (and therefore shouldn’t be able to double-cfick them), but 
they’re an unavoidable -artifact of the current system. 

It should be pointed out that launching an application by double-clicking a file 
containmg configuration data is not necessarily a had thing — it just shouldn’t be 
done with a preferences file. Your application could use an application-specific 
configuration file to allow users to store and set up custom configurations. By 
creating a specific file ty^pe for this information, you make it explicit to users that the 
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behavior of this file type is different from that of preferences files, and that it is 
unique to your application. 

Now let's take a closer look at how to implement the recommended preferences file 
behavior. 

SUPPRESSING LAUNCH UPON DOUBLE CLICK 

As we learned in the previous section, a preferences file isn't intended to be a 
document that users can open and directly interact with in the application that 
created it. So how can you keep users from launching your application when they 
double-click your preferences file? 

Let's take a brief look at how the System 7 Finder handles opening document files. 
Normally, when a user tries to open a document file, the Finder searches for an 
application that has a signature matching the file creator. If the search is successful, 
the Finder launches the application and (if the application supports the required 
Apple event suite) sends an Open Documents Apple event to the application, with the 
document file as a parameter. If the search for die application that created the file 
isn't successful, an alert similar to the one showm in Figure 3 is displayed. 



The document "‘MegalDhizzyftpp 
Preferences” could not be opened, 
because the application program 
that created it could not be found. 


II I 


Figure 3# Application-unavailable alert 


Our problem is that we don't want the Finder to launch our application when a user 
attempts to open its preferences file. One way to strive this (as suggested on pages 
7-29 to 7-30 of Imide Madnto^h: Macintosh Toolbox Essentials) is to register a “dummy" 
application signature that's different from the real signature of your application, and 
then set this signature as the preferences file creator. 

Normally, an application has only a single signature resource and a single bundle 
resource. By creating a second bundle resource with a dummy application signature 
and associating our preferences file with that signature, we fool the Finder into 
looking for a nonexistent application for our preferences file, thus preventing the 
Finder from launching our application when the preferences file is double-clicked. 
Figure 4 shows examples of a normal application bundle resource and a dummy 
bundle resource for the application's preferences file. 

Remember to register both creotors — rhe real one and the dummy one — 
with the Developer Support Center (AppleLink DEVSUPPORT, or Apple Computer, Inc.^ 

Creator/File Type Registration, 20525 Mariani Avenue, M/S 303-21, Cupertino, CA 
95014]/ 

If you use this technique, you should also supply an application-missing message 
string resource — an 'STR' resource with an ID of-16397 — in tlie preferences file, 
WTien the user tries to open a file and the application can't be found, the Finder looks 
for this resource in the file. That string is displayed in the alert that comes up when 
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i BNDL ID ■ 128 friim StdPrersTestern.rsrt ! 


lignatur?: |tstr | 
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Application bundle resource 


! BNDL ID - 129 from StdPr 0 fsT 6 Ster.TT.rsrc I 


Signature: IDMTS | 


8: 1 


(should be 01 


® Siring: © Apple Domputer, Inc. 199S 



Dummy bundle resource for preferences files 


Figure 4. Bundle resources 



This document describes user preferences 
for the application Megalilhizzyfipp. Vou cannot 
open or print this document. To be 
effectiue, this document must be stored in 
the Preferences folder in the System 
Folder, 


»)i 


Figure 5* Can't open preferences file alert 


the user tries Co open the file nnd — due to the dummy bundle resource — fails (see 
Figure 5). 

Now for the catch: There are two ways this mechanism can be circumvented. First, it 
can lie overridden if jMacintosh liasy Open is running. Macintosh Easy Open uses the 
'Iranslation Manager to open a file wnth an alternate application if the application that 
created the file isn’t available. It determines the file type of the file that the user is 
tr\dng to open and then looks for applications that support that file type by checking 
their bundle resources. If no applications can be found that support the file type, an 
alert notilying the user is displayed (see Figure 6). However, if any alternate 
applications are found, an alert allowing the user to open the file with one of them is 
displayed (see Figure 7). WTicn Macintosh Easy Open is installed, one of these two 
alerts will alw ays be displayed in place of the normal application-unavailable alert. 

Because our application has a dummy bundle resource that refers to the file type of 
our preferences file, Macintosh Easy Open will always find the application that 
created the preferences file as an alternate application. Fortunately, the Translation 
Manager provides a mechanism to help us hide our preferences file — the 'open' 
resource. In the ’open' resource, an application can specify to the Translation 
Manager exactly what file ty^es it can actually open, regardless of what may be 
specified in any bundle resources. By creating an 'open' resource that doesn’t contain 
our preferences file type, we can prevent Macintosh Easy Open from trying to open 
the file. 
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'riie Re/, definition for the 'open' resource is given below, 
type 'open* { 

literal longint; /* App signature */ 

integer - 0; 

integer = $$CoiintOf (typeArray) ? Array size 

wide array typeArray { h File types that app can open */ 

literal longint; /* File type */ 

}? 


An example 'open' resource inight look like this: 

resource 'open* (128) { 

'TSTRS 

{ 

'TEXT' 

} 

}; 



The document “MegalUhizzyfipp 
Preferences’’ coufd not be opened, because 
the application '^HegaLUbizzyRpp” could 
not be found. 


Could not find a translation eKtension 
uiith appropriate translators. 


i 



Figure 6. Modified opplication-unovailable alert 



Could not find the application program that 
created the document named "MegaliihizzyRpp 
Preferences”. 

To open the document, select an alternate 
program, uiith or without translation: 


MegalUhizzyRpp 


O 


o 


^ Show only recommended choices 


[ Cancel 


) |[ Open ]l 


Figure 7, Tronsbtion choices olerf 
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In this example, weVe declared that die application with creator TSTR' can only 
open files of type 'TEXT’ — the Translation xManager will not attempt to use this 
application to open any other type of file* 

Oiir mechanism is also circumvented if the file type of the preferences file is PICT' 
or 'TEXT and TeachText is installed* In this case^ the Finder displays an alert asking 
whether the user wants to open the document in TeachText, even if you supplied an 
application-missing message string resource in the file and pro\dded the appropriate 
dummy bundle and ^open’ resource in your application. This is a pretty good reason 
for not using 'PICT' or 'TEXT' as the file type for your preferences file* 

WHAT GOES m A PREFERENCES FILE 

If you find the size of your preferences file breaking the megabyte (or even the 1OOK) 
barrier, youVe probably keeping information in the file that really doesn’t belong 
there* WTiat follow^s are a few thoughts on what to put in your preferences files. 

Keep your preferences as resources. 

As we all know, you can put program data into either the data fork or the resource 
fork of a Alacintosh HFS file. The popular response to the question “What is a 
resource?” is Everything!”, and this is still reasonable advice* It’s fairly easy to design 
structs that mirror the structures of your preferences data, and you can even design 
'TiMPL' resources that will let you look at your raw' preferences data in a structured 
W'ay by opening your preferences file with ResEdit Plus, yoiiVe got the Resource 
Manager to do all the work of finding and loading the preferences data into memory 
for you. MTat more could you ask? 

Keep only global user preferences in your preferences file. 

Bear in mind that some user preferences are global (application or enviromnent 
related) and some are local (document related) — don’t ctjnfiise the two. For example, 
keeping track of the size and [position of every document w indow' that’s ever been 
opened by your application in its preferences file isn’t a good idea (this information 
should be kept w'ith the document file corresponding to the document window), but 
keeping a user-specified default window size and position in its preferences file 4? a 
good idea* 

Avoid keeping inachine-specific information in your preferences file. 

It’s rare that you really need tcj keep information such as the system softw^are version 
or the Macintosh model that your software is running on in your preferences file. 
Your appEcation generally shtuild examine its environment at launch, and take 
appropriate measures at that titne to avoid using features tiiat aren’t supported in the 
current environment. 

Be careful of storing dynamic information in your preferences file. 

A good example of something not to store in your preferences file is a volume 
reference number. To quote hmde M/icmtosh: Fiks^ “A volume reference number is 
valid only until the volume is unmounted — if a single volume is mounted and then 
umnounted, the File xManager may assign it a different volume reference number 
when it is next mounted.” In this example, a better solution is to store an alias to the 
volume of interest in the preferences file. 

Use discretion in deciding what preferences to keep. 

To a large degree, this means limiting user options to those that actually improve the 
overall user experience* The only proven w'ay to find out what those options are is to 
conduct user testing on a variety of interface protoUyjes. It may turn out that while 
you thought keeping track of the last knowm number of documents open during the 
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user’s last session with your application was important, it actually adds little or 
nothing when translated into the user’s experience. 

Don't keep stotic program data in your preferences file. 

A file that just contains a lot of canned program data (such as tax forms) is mt a 
preferences file — it’s simply a program data file, and it should normally reside in the 
same folder as the application. That way, the user doesn’t disable the application if 
she throw^s away w^hat she thinks is simply the application’s preferences file {users 
often do this to cause an application to reset back to its “factory” defaults, which, 
w^hen you think about it, is a pretty nasty w^ay to make users reset a program). 


THE STANDARD PREFERENCES LIBRARY 

We’ll now^ take a look at the standard preferences library, a library fitr creating and 
interacting with preferences files that follow^s all the rules weVe set in the preceding 
sections. The library API consists of 11 calls, described in detail below. 

CREATING AND MANIPULATING A PREFERENCES FILE 

In the routines described here, you’ll notice that a preferences file is primarily 
identified not by its name, but by its creator and file type. This is done to allows you 
to localize the name of your preferences file easily, without requiring any code or 
resource changes. Also, should a user inadvertently rename your preferences file, 
your application can still find it. Because preferences files are identified in this 
manner, it’s important to remember to give each preferences file that your application 
uses a unique creator/file type combination. The search sequence for a preferences 
file is as follows: 

1. If there’s a Preferences folder in die System Folder, search it and 
any folders within it (including nested ones). 

2. If diere’s no Preferences folder, or If no preferences file is found in 
the Preferences folder, search the files (not the folders) in the 
System Folder, 


pascal OSErr NewPreferencesFile {OSType creator, OSType fileType, 
ConstStr31Param fileName, ConstStr31Paraii folderlflame, 

ConstStrJlParam ownerName); 

NewPreferencesFile creates a preferences file with the specified creator, file tyqtc, and 
filename in the System Folder (prior to System 7) or in the Preferences folder (in 
System 7 or later). In the folderName argurtientyyou can specify a custom 
preferences folder in w^hich to put a collection of preferences files; pass nil for this 
argument if you don’t w^ant to use a custom preferences folder. If a folder name is 
provided and the folder doesn’t exist, New'PreferencesFile creates it. Another option 
is to proride, in the ownerName argument, the name of the program (application, 
extension, or whatever) that’s creating the preferences file; if this argument is 
supplied, a custom application-missing message string resource is created for the 
preferences file. 

pascal OSErr OpenPreferencesFile (OSType creator, OSType fileType, 
short *refNum); 

OpenPreferencesFile opens the preferences file having the specified creator and file 
type. You must have created the file with NewPreferencesFile before making this calk 
The preferences file reference is returned in the refNum argument; you’ll use this to 
identify which preferences file you’re operating on when making other calls in the 
standard preferences library. 
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pascal OSErr ClosePreferencesFile (short refNum); 


develop 


ClosePreferencesFile closes the preferences file having the specified file reference* 
ThaFs it. 

pascal OSErr DeletePreferencesFile (OSType creator, OSType fileType); 

DeletePrefereiicesFile deletes the preferences file having the specified creator and file 
type. Be sure the specified preferences file is closed before making this calk 

pascal OSErr DeletePreferencesFolder (ConstStrSlParam folderName); 

DeietePreferencesFolder deletes die custom preferences folder specified by 
folderName, along with any contents. Be sure there are no open preferences files in 
the specified folder before making this calk 

pascal OSErr PreferencesFileExists (OSType creator, OSType fileType); 

PreferencesFileExists simply checks to see If a preferences file having the specified 
creator and file type already exists. You can use diis call to detennine whedier you 
need to create a new preferences file, 

ACCESSING INFOUMATION IN A PREFERENCES FILE 

These routines get or set the indicated resource information in the preferences file 
specified by the refNum parameter. 

pascal OSErr GetPreferencesFileVersion {short reftlum^ short versID, 

NumVersion *nuinVersiQn, short *regionCode, ConstStr255Param 
s hortVersionStr, ConstStr2 55Param longVersionStr); 

GetPreferencesFileVersion returns the contents of the specified Vers' resource of the 
preferences file. Only Vers' ID I or 2 is allowed. 

For those of you wondering why GetPreferencesFileVersfon doesn't simply pass 
o pointer to o VersRec (defined in Fifes,h] instead of possing each of the separate 
fields of a VersRec, ifs because the short version string and the long version string are 
packed In o VersRec (it's possible that the shortVersion held of the VersRec will actually 
contain part of the long version string). GetPreferencesFileVersion takes care of 
unpacking the strings properly, and SetPreferencesFifeVersion takes care of packing 
them properly* 

pascal OSErr SetPreferencesFileVersion (short refNum, short versID, 

NumVersion *]iumVersion, short regionCode, ConstStr255Parain 
shortVersionStr, ConstStr255Param longVersionStr); 

SetPreferencesFileVersion allows you to set the contents of the specified 'vers' 
resource of the preferences file. Only Vers' ID 1 or 2 is allowed, 

pascal OSErr ReadPreference (short refKumi ResType resourceType, short 
*resourcelD, Handle *preference); 

ReadPreference reads from the preferences file the resource specified by the 
resourceType and resourcelD arguments, and returns it in the preference argument. 
If you pass nil as the address of the resourcelD argument or 0 as its value, 
ReadPreference finds the first resource with the specified type in the preferences file. 
If you pass 0 as the value of resourcelD, ReadPreference returns the resource ID 
corresponding to the preference resource it found. 
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pascal OSErr WritePreference (short ResType resourceType, short 

*resourceID, Handle preferenceJ; 

WritePreference writes the resource specified by the resourceType arid resourcelD 
arguments to the preferences file. If you pass nil as the address of the resourcelD 
argument or 0 as its value, WritePreference assigns the preference resource a 
resource ID and returns it in the resourcelD argument (if its address isn’t nil). If a 
resource with the same resource type and ID already exists in the preferences file, die 
existing resource is replaced with the new one, WritePreference checks that there will 
he a minimum amount (the exact amount varies as a function of the volume’s 
allocation block size) of disk space remaining on the volume containing the blessed 
System Folder before actually updating the preferences file; if there isn’t enough disk 
space, the preferences file is unmodified and an error is returned. Note that it’s the 
caller’s responsibility to release the memory occupied by the preference argument; 
WritePreference does not dispose of this memory automatically. 


pascal OSErr DeletePreference (short refNiun, ResType resourceType, short 
resourcelD); 

DeletePreference deletes the resource specified by the resourceType and resourcelD 
arguments from the preferences file. If yem pass 0 as the value of resourcelD, 
DeletePreference deletes the first resource with the specified type in the preferences 
file. 

PLEASE PROVIDE PREFERRED PREFERENCES FILES 
(SAY THAT THREE TIMES FAST!) 

In this article, we’ve explored w'hat constitutes good design for preferences files, and 
we’ve examined a library that helps w^ith implementing preferences files. Armed with 
this know^Iedge and the standard preferences library, you too can add preferences files 
to your application the preferred way! 
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Q 


Fm having iroubk figuring out haw to convert some assmibly n*ap patches for selector- 
based traps into PowerPC native code. Do you have any su^estions for a clean way of 
doing this, ideally so that it works on both 680x0-based machines and the Power 
Machitosh? 


A 


Currently tliere's no way to patch a selector-based trap with a native or fat 
patch. (A list of selector-based traps can be found in the back of Inside Macintosh 
X-Ref.) The problem arises from the fact that each routine associated with a 
single dispatch-based trap can have a different parameter list (that is, a different 
number of parameters and different sizes for each parameter). Basically there’s 
no way for mixed mode to handle the variable stack frame sizes associated with 
selector-based traps. This is the same thing that makes head/tail patching them 
so much of a pain in C. 


We’re in the process of trying to determine whether developers have a pressing 
need to patch selector-based traps with native code. For now, keep all such 
patches in 680x0 code. If a patch to a particular routine is itself very time¬ 
intensive (which is rarely the case), the 680x0 patch can call through to a native 
implementation. 


Q 


r?N writmg a QuickDnra' GX print driver for a plotter ami need to send initialization 
and temtinamn mi?igs to the plouet: How can I determine fiom my dtiver ifPtn 
prhning the vety first or last page^ regardless of the number of copies? Fd like to have 
this infifynation in GXStintSendPage and GXIunishSejidPage^ respectivelyy so that I 
can send my strings then. 


A 


We recommend that you do any pre-first-page setup in GXO pen Connection 
(after forw^arding) and any post-last-page teartiown in CiXCloseConnection 
(before forwarding). (Although the documentation is a bit ambiguous on this 
pf)int, you can send information with GXBufferData and GXWriteData from 
GXCloseConnection, before forwarding.) If there’s some reason that this w^on’t 
work tor you, and you really need the information in CrXStartSendPage and 
GXFinishSendPage, yoirll have to use global data. 


In some override before GXStartS end Page (perhaps GXImageDocument), 
mitialize a global page counter to 0. In your GXStartSendPage override, check 
tliis flag, and then bump it after forwardi ng. If your check finds that die flag is 
0, no pages of the document have been sent yet. 

To determine when the last page has printed, you’ll also need to use global 
data. Somewhere (again, GXImageDocument is fine) call GXCoontPages, get 
the number of copies from the job’s 'copy' collection item, and multiply. In 
your GXFinishSendPage override, compare the %ulue you bumped in 
GXStartSendPage to this multiplied value. When they’re equal, you’re just 
finishing the last page. 


Q 


How do client and setwe^r desktop printefy (shared printers) synchronize in QuickDf^aw 
GX? Specifically^ what we^re trying to fhid out is (for a server desktop printer on one 
tnachme, and a matching client on another): 


• If a user on the client ?nachine sets a papertype in an input tray, is it t^fiected on the 
server in the Input Trays dialog? If not^ whaFs the cotrect behavior far the client 
and the server machines (far exmnpky should the client Input Trays dialog he read¬ 
only)? 
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• Gcnrmliy^ what resources and data are transniitted between the host mid the client^ 
and when? h there a mechmiimi for contrallhig which resomxes will be sent or kept 
load (preferably on a resource-by-resonrce basis)? 

Resource.4 are tranmiitted to desktop printers in only one direction — ser\'er to 
clients. Also, only resources with IDs greater chan 0 are moved to the clients. 
Therefore, ids appropriate to make the Input Trays dialog on clients read-only. 
Even though Apj^le’s drivers don’t do this, it’s the more correct approach. You 
can find out whether you’re on a server or a client by checking the desktop 
printer’s comnd resource; if its type identifier is 'ptsr', you’re on the client; 
otherwise, yoii’re on the server. 

If you need to have data sent from the client to the sender, you should fetch the 
resources at GXImageJol) time (before forwarding) and then roll them into a 
job collection item. In the appropriate communication message, look for the 
collection item and use that data. Since GXIniageJoh is always called (shared 
printers or not), and it’s called on the client if you’re working with shared 
printers, this method should always wwk. 


Q 


If I want to add additional ptvpenies to the paper stock (such as paper color)^ and I call 
AddCollectionltimf(GXGetlhiperTypeColkcrion(paper)^ - - A that new collection be 
stored in the desktop printer^* configwrationfile^ or is that something I must mariage? I 
seem to he losing ?ny collection between invocations of the Trays dialog. 


A 


The papertype collection items you add won’t he flattened to disk and stored in 
the desktop printer via your Trays dialog, 'rhere’s no way to make collection 
item changes and have them saved with the disk-based papertype, wherever it 
may be stored. You need to manually save the information in your desktop 
printer (or some other place) as resources, and then match that up with the 
papcrt}q>es when you w^ant to use them. You should match up the papertypes 
and the resources based on the names of the papertypes. 


You can still take advantage of the papertype collection to hold your paper color 
information, as long as you also have the infonnation stored on disk. The 
papertype collection will be around as long as the paperu^e’s job is around. For 
example, if you load the color info from die desktop printer and put it in a 
papertype collection item at despoolpage time, it stays there throughout the 
entire print cycle, and wherever the job goes, it goes. 


Q 


Tm having a problem resizing text elements in our QuickTime application. Tm trying 
to modify the elements size by calling SetTrackDimermons, and it see?ns to do what I 
want for ali eletimit types except text For text trmkj^y the elements boimdmg box is 
resized eoiTectly^ hut the texv characte^rs are saiinched into the upper left corwer of that 
rectangle, still at their original size. In other wo^rds, SetTrackDimensions seems to scale 
the track bounds, but not the text characters themselves. Any idea whai's going oti? 


This is a bug. As you determined, SetTrackDimensions is only changing the size 
of the track box, not setting the correct scaling factor or in ternal flags. To work 
around diis problem, use GetTrackMarrix to retrieve the current matrix, then 
ScaleAlati'ix to change it, and finally SetdrackiVIatrix to make it take effect. 


Q 


Do you knoic why ''^OCE Alail Enclosures'^ appears as a volume when I index through 
all volumes using PBHGetVlnfo? Is there any way to filter out this \wlume"? 
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A 


The reason “OCE MaiJ Enclosures” shows up is that it's the volume for an 
external file system (XFS) that AOCE installs in order to support access of letter 
enclosures via FSSpecs from the mailer and otlter parts of the AOCE system. 
This enables the direct access that the mailer provides in the enclosure fields of 
letters^ allowing users to manipulate enclosures like any other file in the Finder, 
coptdng and even launching them directly from the enclosure pane. 


To filter out the “OCE Mail Enclosures” volume, you should check the Finder 
flags of the root directory in each volume to determine whether that volume 
should he visible to the user. The Finder flags for directories are located in the 
ioDrUsrWds field in the dirinfo variant of the CInfoPBRec structure. If tlie 
flnvisible bit is set, you should not display that volume to the user. Here's a 
snippet: 


void inain(void) 

HVolumeParani 

CInfoPBRec 

Str255 

OSErr 


pBlock? 

cBlock? 

volName, fRame; 
err; 


pBlockToRainePtr = volHame? 
err = noErr; 

for (pBlock.ioVolIndex^l; err—noErr; pBlock.ioVolIndex++) { 
err = PBHGetvrnfo({HParmBlkPtr)&pBlock, false); 
if (err==noErr) { 

cBlock.dirlnfo.ioRamePtr ^ fName; 
cBlock.dirlnfo.iDVKefNum = pBlock.ioVRefRum; 

// Query the directory info ioDrDirlD, 
cBlock.dirlnfo.ioFDirlndex = -1; 

// This is the root directory. 
cBlock*dirinfoToDrDirlD = 2; 
err - PBGetCatrnfo(ScBlock, false); 
if (err^-noErr) { 

if [ {cBlock.dirInfoToDrUsrWdsTrFlags & 
flnvisible)J=0) 

// It's invisible. 


} 


} 


Q 


I have a dialog with two editText fields. When / popnlatc the two fields with text, 
wbkheva* field I poptilate fnst is displayed two pixels too high within its itertL The 
second field is fine, and it has the fioais^^ of the dialog. IVhen I click in the first field, 
any new text is added at the connect height, Imt imfhnunately thaTs nvo pixek Mow 
where the previous text was drawfh The fields arc both 10-point plain Geneva, and the 
cditText boxes are 16 pixels high. Any ideas? 


The Dialog Manager has a bug that causes problems when you use an alternate 
font or size for the editText items. The problem is how^ it draws the text initially 
in the dialog: the text for the currently active item is drawm by manipulating the 
dialog's TextEdit record, and the text for all other items is drawn by calling 


94 


develop issue Ifl June 1994 





TextBox. The solution is to call SellText just Iiefore you call SetIText each time 
you populate a field with text. 


Q 


How can I conven an RGB color into an Index to a pahtte axated by my applkationl 
Colorllndex con:V€rts the RGB color to an index to the mtTcnt deviads color table^ hut 
thaRs not what I want. 


'rhere’s no single call that will give you a palette match to an RGB color. You’ll 
have CO do this: call Colorllndex to get the closest match to your RGB request; 
call Index2Color to get the device’s indexed color from your match; search the 
palette yourself to find the color match {according to RGB value); and call 
CoIor2Index to verify that you have the color you’re looking for. 


Alternatively, you can create an off-screen GWorld, call Palette2CTab to 
convert your palette to a color cable, and call UpdateGWorld to insert your new 
color table in your off-screen GWorld. Then, to find the index of an RGB 
color, make your GWorld the active device and call Color2Index, 


Q 

A 


Vve t?'ied in vain to fijid a way to print white text o?i a hiaek background, b there a 
way to do this, and if so, how? 

The trick is to use the srcBic pen mode: 


FillRect(theRect, black); 
PenModefsrcBic); 
DrawString(myString); 


Q 


In our application, the user can select an area of a?j miage and drag it around. 17vant to 
show this visimliy by inverting the region under the cuire?it mouse coordinate as the 
mer moves the mouse around. Invetting the region is nice because I can invert it again 
to get the unselectedpixels back. It's not nice, however, m that a ^0% gray color looks 
the same when ifs invefted. To fix this problem, I ttied u.ung Paint Rgn with an 
RGBForeColor ofr,g,b = OxSOOO and a tf^ansfer ?node of addOven This works great on 
24-bit screens, but it sevms that on 2S6-color screens, applying this ope^^ation twice 
doesn 't quite retmn to the original colo7\ Am I going to have to use a custotn color 
seai'ch procedim? 


A 


You get the results you want on direct devices but not on indexed ones, and 
unless you’re extremely lucky with your color table, this is how it will always 
work. Idle problem is that the mode calculations are done with the actual RGB 
values used (the ones available in the color table), not the ones you request. On 
indexed devices there’s almost always a difference between the tw^o, so unless 
your color table happens to have the exact color you request, there will be 
“errors.” 7'his never happens on direct devices because all colors are available — 
the operations work on direct RGB values and are never mapped through color 
tables. 


The solution is either to set up your color tables or palettes to make sure you 
get the results you want each time, or to install a custom color search procedure 
if that’s w'hat you’d prefer. 


Q 


After we call CMOpeti and a connection is established, a dialog is displayed and 
evmtually goes away. Unfortunately, the C++ object fimnework we use is bombing 
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because ifs getting a deactivate event fo?^ that wmd(m\ which belongs to the 
Communications Toolbox. IVe unvote a kludge that sets a flag after the cal! to CM Open 
is finished and eats the deactivate event if the flag is set. Is there a better way for m to 
tell whethei- to let the class lihvry handle the event or to handle it ourselves? 


A 


A window or dialog created tiy a connection tool has the connection record 
handle stored in the refCon field. The sequence, then, is to check the event 
record to find out if the event is tied to operations in a window' and, if so, check 
the window’s refCon against your connection handles. If there’s a match, call 
CAlEvent for that event; otherwise pass iron to the framework. You’ll probably 
need to write a handler for your class library to do this properly, overriding the 
default window-handling routines for this special case. 


Q 


U'ljen our application opens a Commimicatiom Toolbox tool, we issue a CMOpen with 
the asynch-o?iom fiag True and go into a loopy calling CMIdk atul then CMStatm imtil 
we see the crnStatmOpcnmgflag go down or the cmStatiLsOpen flag come up. When we 
use the Express Modetn Tool (on a Macintosh Duo 230), those flags never change. 
Should we be doing something diflh*ent or is there a problem 7vitb that tool? 


A 


The Express Modem Tool uses a background process (coupled tightly with the 
hardware implementation) to actually move data. Unless your application yields 
processor time thrt^ugh the WaitNextEvcnt cycle, the backgrcmnd process is 
stuck w'hen you call the tool asynchronously (The synchronous call has been 
massaged to give the process time, of course.) 


WTiat you’re doing, essentially, is making the asynchronous call synchronous by 
trapping your application in this kind of loop. 1'he proper thing to do would be 
either to use the call synchronously or to continue to use it asynchronously but 
exit back to the main event loop and look for the Hags from there. V\'Een the 
appropriate flag is set, you can then dispatch off to a handler routine. Even 
better, use a completion routine to notify the application tiiat the CMOpen has 
completed and obtain the function result from the OmnHandle errors field. 


Q 


Eve hnpleniented a vaiiant of the CMChoose dialog hmed on the Choose.p sample code 
m Inside the Macintosh Conmnmications Toolbox\ page 323. Theprobkm I have is that 
all the fields of the dialog appear in l2-pQmt Chicago rather than the 9-pohn Geneva 
that tool dialogs usually use, so the dialog looks really tacky. How can I fix this? 


A 


The critical thing is knowing wEen and where to set the window^ text 
characteristics. Tools provide a resource (Tnf or 'flst\ defined in SysTypes.r 
and CTBTypes.r) that gives you the font information for the tool’s DITL, 
Between the CMSetupPreflight and CAISetupSetup calls, you should fetch the 
font, size, face, and mode from the resource and set your custom dialog’s port to 
match it. You also need to stuff the same information into the dialog’s TextEdit 
record so tliat the editable fields show up correctly. Ctjutrols provided in a 
DITL by Communications Tciolbox tools have the useMTont bit set so that 
they always follow the settings in the dialog’s port. 


Q 


WeTe calling CMListen synchronously in our application, and if it times out an aror 
alen is displayed that doem ’f go away until the user clicks OK (or after a ve^y long 
tmie). h it possible not to have this dialog displayed, or to hiwe it go away quickly as the 
^onnected"^ dialog does? 
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A 


With regard to all Cominunication?> Toolbox interface components, you can 
only leave them all on or turn them all off with die flag parameter to CxMNew 
(cm Quiet and cm No Men us). We don’t know of any way to affect the behavior 
of specific elements like the error dialog raised by CMListen. (CMListen is best 
implemented in an application as an asynchronous call, particularly in the 
cmQuiet mode,) 


Q 


The Connectmi Manager sample code in hiside the Mncintosb Communications 
Toolbox sets the bnjfer sizes for anDamin and cmDataOnt to IK and the rest to 0^ and 
therTs a cmmmnt that the other channels are to he ignored. Then, in the desaiption of 
CMNem^ itsays^ “To have the tool set the size of these bujfers, your application should 
put zeros m the an^ay. ” Whafs the recammended way to go? 


A 


You should consider the buffer sizes you set in the C^M Buffer Sizes array as a 
request for buffers. The toors implementation will always override your choices 
based on what the developer felt was the proper thing to do. Many 
programmers initialize the array to all zeros and let the tool defaults be set; 
there’s some argument for increasing the sizes on netw^ork protocols for 
efficiency, but it’s up to the tool designer to determine what makes the best 
sense. Rather than depend on any particular buffer sizes in your application^ you 
should deal with what the tool allocates dynamically 


Q 

A 


What is that ^een slime that you mn buy in toy stores made of? 

We’re not exactly sure what the composition of that stuff is, and the toy 
companies aren’t about to tell us, but we’re pretty sure that it’s some sort of 
polymer that’s cross-linked via hydrogen bonding. Hydrogen bonds are 
relatively weak, and can be easily pulled apart. That’s why these materials 
behave like “sIom^ liquids” and eventually seek their own level. 


A very satisfying w^hite version of slime can be concocted at home from 
common ingredients as follows: Mix 1/2 cup water and 1/2 cup white glue in a 
bowl. In another bowl (or a cup) dissolve 1 teaspoon borax in 1/2 cup water 
(make sure the borax is completely dissolved; it may take a minute of stirring). 
Pour the borax solution into the glue solution, stirring rapidly and constantiy 
Keep stirring for a minute; then reach in with your fingers and keep mixing, 
mdng to breakup the lumps. At first the material will be lumpy and wet, but 
soon it will become smooth and rubbery. This recipe makes a blob tlie size of a 
grapefruit. Use less water with the glue for stiffer slime. Store in an airtight 
container, and keep it away from carpets! 


Q 


Nothing m the documentation for MacTCF deals with the state of register A5 if an 
ioCompletion routine is specified within struct CntfiParam (MacTCP version LI 
docu^nentation, page 1). Pve been manually preserving and setting A5 with some hiline 
assembly code but wonder if this is really necessaty. If I must set AS ^ and want to use the 
same source code in the 680x0 and PowerPC ejwironments^ how do I go about it? 


Wlien MacTCP calls the application’s ioCompletion routine, it restores the 
application’s A5 register, so the application shouldn’t worry about this (the 
MacTCP driver takes care of it). On a Power Macintosh, you can still set 
register AS in the emulator as you did before (with SetAS and SetCurrenL^S). 
However, be aware that with native code, register A5 is no longer used to store 
references to global variables. Any piece of PowerPC native code, even 
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Standalone code, can have its own global variables without making its own AS 
world. 


Q 


When a dnvej^ is operating synchronomlyj what kinds of system calls are prohibited? 
Specifically^ caai I make memory allocation calk and file system calls from the driver? 


A 


If your driver is called synchronously, you should be able to allocate memoiy 
and make file system calls and other system calls diat move memory. If ids called 
asynchronously, you should ?iot make diese calls. There's one important 
excepdon to this guideline: the Macintosh file system isn’t reentrant, so in a disk 
driver or a network driver that serves the file system, you must not make any 
calls to the file system, as you will tie it into metaphorical knots. 


Q 


r?n creating an applkamn frmn an existmgfde by adding CODE resources to it, 
setimg the Inmdle bit, clearing the inired hity closing the file, and flushing the volume. 
My probk?n is that the Pinder doesn't reco^ize the change immediately. / have to 
move the file to anothe'r folder before the icon changes and ifs recognized as an 
application. Wljat do I need to do to have the Finder recognize the change immediately? 


A 


The problem you’re having stems from the fact that the Finder only scans for 
changes about every 10 seconds. To make the Finder aw'are of changes before 
that, you need to change the modification date of the parent directory. Use a 
routine like this: 


OSErr TouchDir(short vRefHuirii long dirlD) 

{ 

ClnfoPBRec info; 

Str255 name; 

OSErr theErr; 

info*dirInfo,ioDrDirID = dirlD; 
info.dirinfo.ioVRefNum ^ vRefNum; 
info.dirlnfo.ioNamePtr ^ name; 
info.dirinfo.ioFDirIndex = -1; 
theErr ’ PBGetCatInfo(^info, false); 
if (itheErr) { 

info.dirinfo.ioCompletion = 0; 
info.dirlnfo.ioDrDirlD = info.dirlnfOiioDrParlD; 
info.dirlnfo.ioFDirlndex = 0; 

GetDataTime(&info.dirlnfo,ioDrMdDat); 
theErr = PBSetCatInfo(&infO| false); 

} 

return theErr; 

} 

The Finder will rescan the specified directory immediately after this routine 
updates the modificadcm date, usually w'^ell widiin one second. 


Q 


Does the idleProc ofAESend get called before every event is sent, even those to the 
cufTentprocess (which are directly dispatched)? IVhat I really care about is whether 
W/irNextEve7tt is called each time. 


AESend’s idleProc will be called if kAEWaitReply is the sendMode. In diis 
mode the Apple Event Manager uses the Event Manager to send the event. The 
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Event Manager then calls WaitNextEvent on behalf of your application. This 
causes your application to yield the processor, giving the server applicatioji a 
chance to receive and handle the Appde event. You must supply an idleProc in 
order to process any update events, null events, operating system events, or 
activate events that occur while your application is waiting for a reply. 

If you use kATNoReply or kAEQueueReply as the sendMode, AESend will 
immediately remrn after using the Event Manager to send the event* Your 
idleProc will never be called (in the case of kAEQueueReply, it's assumed that 
you want to receive your reply via your application's event queue, and you must 
install a handler for the reply Apple event). 

Likewise, your idleProc will never be called in the case of a direct dispatch. In 
doing a direct dispatch youVe sending an Apple event to yourself using die 
typeProcessSerialNumher and kC^urrentProcess. These events are delivered 
directly, bypassing the event queue and executing your handler routine directly. 
For more information, see the Macintosli Technical Note ''SendToSelf: Getting 
in T)uch With Yourself Via the Apple Event Manager” (Interapplication 
Commiinicarion 1). 


Q 


Fm having a pmbkm sending cimmn Apple events over the network. We have a 
haekg?v//nd-on/y application on one rnachine setiding cmto?n Apple evetJts to another 
mnchme via hocalTalk. If we mamudly pull the LoealTalk cable out from the back of the 
sending Macmtosh.^ the event is never received 07t the remote machiney but an envr is 
never returfied by AESe?rd. AETracker logs show that the eifent is being sent with no 
erroVy hut AETracker o?i the remote machine shows sigft of the et^ent. We^ve also seen 
a similar thing happen when phone lines are bad. Note that in both casesy other events 
are sent between the machines Just fine. What givesi" 


The reason jAESend doesn't report an error in cases like the one you mention is 
l)ecause it can't* As soon as the event is sent, iAESend returns noErr indicating 
that the event has been handed off to the PPG Toolbox for sending* YouVe then 
back in your main event loop and doing other things* If for some reason the 
connection goes down (or there's any odier transmission problem), there may 
he a resulting eiTor from die network layer that's actually transporting the 
event, hut the resulring error may not occur for seconds or even minutes. At 
that point there’s no way for die AESend diat sent the event to detect die error* 


We saw^ a good example of this recently using a standard Ethernet connecdoii 
between two machines. The network connection w^as broken between the 
machines and an event was sent from one to the other. AESend returned noErr 
on the sending Macintosh, and as long as we reconnected the two machines 
before the end of the associated timeout period — tw^o minutes ^— the event was 
received* If we waited longer the event never made it. But in either case iVESend 
returned noErr* 


There are a couple of ways to address the problem* The First way is to use 
kAEWaitRcply when sending your event; however, you give up the processor in 
favor of ensuring a reply. The other solution is to pass LAEWantReceipt in the 
sendMode parameter of AESend and have a timeout for the amount of time 
you're willing to wnit for a reply. 


Q 


We have tw^o c/uestions regarding AppleScript. Firsts whafs the .ngnificance of Begin 
Tra?2sactio?7 and End Transaction for a single-threaded application? Do we need to 
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support these two ri^ents If we dou send eiftms or scfipts to another applkatmi? The 
Apple Event Reglstiy says to ret my? a rramaction ID for the Begin Tramaetion call 
and to check for the tf*ansaction ID of all the incofning Apple evenu. Is this really 
necessary? Second^ whafs the user intefface guideline for the Prmt Document fpdoT) 
event in the required suite? Currently, I hring the application to the front by calling 
AEInteractWithUsef^ (only if both the sefwer and the client are in the same machine) 
and open the piint job dialog box. 

A single-threaded application doesn’t need to support Begin or End 
Transaction, If you need transactions, you may implement them as you see fit. 
Regarding the 'pdoc' event, what you’re doing is correct. WTien you receive a 
■pdoc' event, you should call AEInteractWithUser and check the result: if you 
get noErr (meaning you can interact), open the standard print job dialog; if you 
get ernAENoUserEiteraction (you can’t interact), just do whatever the default is 
for that document, printing without interaction. 


Q 


Tin doing a project where I need about 1 SOOKfor my own off-screen GlVorlds and 
sund'f j data striiaures^ and we^re targeting the 4 MB Macintosh LC. Hirers the 
kicker: we need Text to Speech. Ed like to hum more precisely how the memory 
allocation works in the Speech Manager so that I know what our options are —for 
example, how much memofy gets allocated fi‘o?n the system versus how much from my 
application heap. 


A 


Wien trying to preflight the memory'' needs for an application that uses Text to 
Speech, keep in mind that there are at least three different managers involved in 
the production of speech on the Macintosh: the Component Manager, the 
Speech Manager, and the Sound Manager. All these have their own memory^ 
allocation schemes and take memory from different places. 


a rough rule of thumb, to use Text to Speech in a robust nianner, plan on 
adding 250K for each SpeechChannel you expect to keep open at any given 
time; this should accommotiate both Macifflalk 2 and MacinTdk Pro voices. If 
this causes a minimum application siz.e that’s not acceptable, you can add only 
50K for each MacinTilk 2 channel you allow to be open at a time and include in 
your documentation instructions on how to increase the size if the user decides 
to use MacinTalk Pro voices instead. 


The more complete scenario goes like this: The Component Manager takes up 
about 20K fjf the system heap (possibly slightly less w'heii no components are 
open). The Speech Manager code and data use around 20K of system heap, and 
should be a one-time investment (note that little variance should he expected 
from version to version). The Sound Manager memory usage depends on the 
version and other factors, but a good estimate is 3OK per SndChannel. Note 
that the Sound Manager code goes into the system heap, with sound buffers and 
sound data being allocated in the application heap. 

The amount of space needed for the Text to Speech engine code and data (such 
as pronunciation dictionaries and rules data) varies quire a bit berw^een 
MacinTalk 2 (about lOOK) and iMacinTalk Pro (about 300K); this memoiy is 
allocated in the system heap whenever possible to make it available to different 
applications using the same engine. If the Speech Manager can’t allocate the 
necessary space in the system heap, it tries to get it from the application heap. 
Naturally when tliis happens the code and data cannot be shared across 
applications. There’s also some Text to Speech engine^specific SpeechChannel 
data whose size varies from engine to engine: xMadnTalk 2 uses roughly lOK 
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and MacinTalk Pro uses about 175K. Finallvi there’s the voice data and code: 
Macin'ralk 2 takes between 20K to 4^)K depending on the chosen voice, while 
MacinTalk Pro voices can use hemeen 3{K)K and 2.25 MB of R.\iM. Again, the 
memory' needed for voice data and code is allocated from the system heap if 
possible to allow sharing between applications using the same voices; if there’s 
no room in the system heap, the Speech Manager tries to load this in the 
application heap, and no sharing is possible. 

Finally {you knew this was coming, didn’t you?), be aware that these numbers 
may change in the hiaire. Use them as a guide, but as always, don’t depend on 
them. 


Q 


What should we do ivheii renaming a doamrent that contaim a publishej- section? / tty 
to call AssociateSection with the already registered section and the nni^ FSSpecPtr 
AssociateSection retutTis no etror and 1 unregmer the puhlisher section. But the tiext 
time 1 open up and register the puhlisher section of that document, I get a -46 J en'or 
code on RcgisterSection, H^at am i doing wrong? 


AssociateSection doesn’t change any information in the edition container file, 
which is w^here this needs to be changed; it only acts on the “hot” links the 
Edition .Manager is currently maintaining with any open documents that are 
using a section . WTiat you have to do if you rename a publisliing document is 
to open the publisher and update it. V\^en you call OpenNewEdition with the 
new file name, that w5ll update things. This means that a “save as” must dirty 
all your publisher sections, which shws you dow'n a bit and may be 
counterinaiitive. Bur the only other option would he to update the alias 
direedy, and that would be bad. 


Q 


Vni irorking on a video-confei'eming solution that uses the video digitizer (vdi^ 
incorporated in the Macintosh Quadra S40AV. 1 want to capture data front the systenFs 
huiltAn video hardware using the PT>CompressOneFra?ne and FDCompressDone calls. 
1 have the followmg questions ahout the vdig that supports the 840Ay built-in video 
hardware: 


• Wlsafs the header and data foiwat for the capttmd video? 

• WhaFs the compressor type (cType) for this compression format? 

• Does this cotnpressor support more tbati one spatial compression setting and, if so^ 
what are the data formats for the compression settings? 


A 


Wt can’t provide information regarding the data format of the captured video. 
It’s considered proprietary^ and confidential, except in cases w^here the codec in 
use is an industry^ standard like JPEG, Fortunately, you don’t need to know the 
data format if you’re using the correct QuickTime vdig and Image Compression 
Manager calls to manipulate the data. 


We don’t think you should use the vdig direedy, but if you do, you can call 
VDGetCompressionTy^e to determine the compression types it supports. You 
cau select the compression type you want to use by calling VDSetCompression, 
Since the vdig uses standard codecs for compression, you don’t need to know 
the data format; all you have to do is use the codec to decompress the image 
data w^hen you want to draw it. Call VDGetImageDescription to get an image 
description handle, which you can pass to Decompresslmage along with a 
pointer to the data, and the Image Compression Manager will take care of 
decompressing the data as long as the correct codec is available. 


MACINTOSH O & A 


101 






We don’t recommend using vdigs directly because every one is different and 
supports different features. They can be pretty hard to work with because your 
code will require a lot of error handling and workarounds. The sequence 
grabber was written to provide a seamless interface between any vdig and 
applications, so you can use the sequence grabber as the engine for your video- 
conferencing system. It was designed with this kind of flexibility m mind. For 
more information about the sequence grabber, see Chapter 6, “Sequence 
Grabber Channel Components,” in Inside Macintosh: QuickTime Components. 

Using the sequence grabber with the right flags, you can get high-performance 
grabs, even over the network. You do this by supplying application-defined 
functions to the sequence grabber component. If you replace the grab function 
on the receiver side, you can use the sequence grabber to grab right off the 
network on that end. On die sender side, you can replace the data function so 
that you’ll be able to write the frames out over the network, using whatever 
network protocol you like. 


These answers are supplied by Apple's 
Developer Support Center, Special thanks to 
Brian BechteJ, Matt Deofherage, Godfrey 
DiGiorgi, Steve Falkenburg, Dove Mersey, Dove 
Johnson, Scott Kuechle, Joseph Maurer, Kevin 


Mel lender, Jim Mensch, Martin Mi now, Gut Her mo 
Ortiz, and Brigham Stevens for the materiol in 
this Q & A column. If you need more answers, 
take a look at the Macintosh Q & A Technical 
Notes on this issue's CD.* 



Your main source for Apple development products 

Gel easy access to New inside Macintosh and over 200 other programming products, t(X)Is, technical 
resources, and information through APDA, Apple’s worldwide source for Apple and third-party 
development products. 

Ordering is easy, and APDA offers convenient payment and shipping options, including site licensing. 

Call for additional information on APDA or recently announced products, or to request a complimentary 
copy of ih.e APDA idols Catalog. 

Call APDA today. 

United States 1-800-282-2732 
Canada 1-800-637-0029 
International (716)871-6555 
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Newton 
Q&A: 
Ask the 
Llama 


Q 


Here^ .wmething thaf^s l?eeJ7 puzzlmg me a bit: I want pop up smtiething like a 
copfyright tmssagt for ten semnds when my application stans up. Sq I drewc up a layout 
called Presents with a protoFloater comaining all the necessary text. In my main layout 
is a link to Presmts called presentsLink. The following b the virwSbmvSaipt for the 
topmost view in my application: 


fanc() 
begin 

presentsLink:open(); 

AddDelayedAction(presentsLink:close(), nil, 10000) 


This says to me: open the linked viemSj wait ten seconds^ and close it. A?id thaPs exactly 
what it does, except that after the view is closed, there's an exception. iVhat am I doing 
wrong and herw do I fix iti' 

A The short answer is that the second argument to the AddDelayedAction 
fujiction is of the wrong ty^e. This argument is supposed to be an array of 
parameters to be passed to the delayed function, and nil is not an array The 
proper syntax for no arguments is [J instead of niL 

But there’s more: Although the closure you supplied in the first argument works 
in this case, you should get out of the habit of using that ty^e of function call for 
delayed or deferred actions. You’re better off pro\iding a full closure and 
sending in the view you want dosed, as in this: 

func () 
begin 

// Define a closure to use in the delayed action, 
local myClose := func{whichViev) 
whichView:Close(J; 

presentsLink:Open(); 

AddDelayedAction(myClose, [presentsLink], 10000); 

end 

Unfortunately, things do not end there. You also need to make sure that the 
myClose function is in internal RAM, The best way to do this is to use 
DefConst to define the function: 


//In your ProjectData file; 

DefConst (' kDelayedClose, func {whicliView) whichView: Close ()); 

if This changes the function above: 

func() 

begin 

presentsLink:Open(); 

AddDelayedAction(Ensureinternal(kDelayedClose), 
[presentsLink], 10000); 

end 


The llamo is the unofficial mascot of the 
Developer Technicol Support group in Applets 
Personal fnteradive Electronics (PIE) division. 
Send your Newfon-reloted questions to the PIE 


Homo of AppleLink DR.LLAAAA |on the Internet 
dr.llama@applelink.applexom). The first time 
we use a question from you, weMI send you o 
T-shirt.* 
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Howevtir, there is an easier solution. Instead of doing a delayed action you can 
use the \iew idle mechanism to do what you want. All you need to do is add a 
viewIdleScript and viewTdleFrequency to the presenCsLink top-level view. The 
viewIdleScript simply sends a Close message. The viewIdleFrequenq^ is set to 
the desired delay (1OOOO in this case). 

The really short answer is that yon can just use protoGlance. This proto has the 
show-and-disappear behavior built in. You can set the viewldleFrequency to 
10000 to get the behavior you want. 


Q 


/ have an aiphalwtkally sorted list of items in a pratoTahle and I want to use protoa2z 
to ffikkly move through the table (like the cardfile ovefvdew). How do 1 do it? 


The first thing you need to do is find the index in the protoTable of the correct 
item (that is, find the right item in the def.tabValues array of the protoTable), 

I low you do this will depend on what type of data youVe representing, I'hen 
you can figure out how high each item in the protoTable is, set the TOrg slot of 
the table to the correct line, and force the protoTable to redraw. You probably 
want to make sure that you don’t scroll off the bottom of the table. Below is a 
method you can add to your protoTable that will do what you want. You can 
then send the message horn your a2zChanged method (make sure you send the 
message to the protoTable), 


func ^index) 
begin 

// Figure out the height of an item in the table- 
local childHeight := if def*tabProtos.viewFont exists then 
fontHeight(de f.tabProtos.viewFont) 
else 

fontHeight(viewFont); 

// Make sure that the table will not scroll off the end 
//by calculating the index of the bottoinmost item that 
// will be displayed, 

local largestIndex def*tabDown - ((:LocalBox{).bottom - 

:LocalBox()itop) DIV childHeight) - 1; 


// Use the bottommost item (largestIndex) to make sure 
// the table has no empty space on the bottom* 
vOrg MIN(index, largestindex); 

// Now force the table to redraw, 

:RedoChildren(); 

end 


Q 


/ would like to use the protoalz sample code in my application, bm I cank figure out 
how to set the highlighted letter when the user scrolls through my data. 


It’s easy once you realize that protoa2z is based on a protoPictlndexer. All you 
have to do is a SetValue of the currlndex slot to the correct index. This will 
change the highlighting of the protDa2z, 


Note that using SetValue will not call the IndexClickScript, but this is probably 
what you want. If you do w^ant it to be called, you’ll have to manually 
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unhig^hlight the current selection, set the currlndex slot, and then highlight the 
new item. The apprcjpriate code w^ould be 

a2z jUnhilite{); 

a2z>currlndex := newlndex; 

a2 % X Hiliter(newlndex)? 


Q 

A 

Q 


What is yQUr quest? 

To answ'er the questions of those w ho develop for New'ton* 

/ tried to use a promPietRadioButton in my applkatmi hut the highlight 7*ectangle mft 
the Hgbt sis^e. I know that I need to write sofue code to draw the correct-sized highiigbp 
hut where do I hook it in? 


A 


Minimally you need to override the view^DrawScript of the procoPictRadioButton. 
You may also w^ant to change the viewFormat since it defaults to a thick rounded- 
rectangle border. Assuming that you wanted some sort of rectangle highlight 
around the selected button, you could use the following \dewDraw^Script: 


func{) 
begin 

// If the button is selected, highlight it, 

if viewValue then 

begin 

// Get the bounds of the protoPictRadioSutton* 
local b ;= :LocalBox(); 


// Inset the bounds, 
bitop bitop + 
b.left b.left + 2; 
b.bottom t=^ b.bottom - 2; 
b.right b.right - 2; 


// Now draw a rectangle, 

!DrawShape(MakeRect(b.left, b,top, b.right, b.bottom), nil); 
end; 

end 


Q 

A 


Wljat is the AutoCIose checkbox in the Newton Toolkit for? Why should I use it? 

The AutoCIose flag causes all other AutoCIose applications to be closed when 
your application is cUcked. The effect is that only one “auto-close” application 
can be open at one time. You should always make your application auto-close, 
to help conserve memory and other resources, unless it^s providing special 
functionality to other applications (like the built-in Calculator or Styles 
application). 


Q 

A 


H(tw do 1 create my ow?t class of binary object? 

To get a binary object of your own class, you first need to create a binary object, 
then change its class to your owm. The easiest way to do this is to create a string 
that’s the same length as your intended binar)^ object and then change (coerce) 
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the class of this new object to your own class. You can use the string class as 
your basic binary object. 

Suppose you wanted to have a binary class called CharlD for an ID consisting 
of four ASCII characters. You could write a NewID function in your 
ProjectData file that w^ould create the object and optionally initialize it, like this: 

// Define a constant for a default CharlD object. This constant 
// can be cloned at run time, kDefaultCharlDObj will be a CharlD 
// object with 4 bytes that are set to 0x00, 

DefConst ('kDefaultCharlDOBj, SetClass(SetLength(", 4), 'CharlD )); 

// CharString is a string of 4 characters or nil, 

NewCharlD i= func(CharString) 
begin 

// Create a binary object of the correct length, 
local newObj := Clone(kDefaultCharlDObj); 

// Optionally initialise it. 
if CharString then 
for i 0 to 3 do 

StuffChar(newObj, i, CharString[i]); 

// Return the new object, 
newObj; 
end; 

'lb see this code in action, you can type it into the Inspector window^ in the 
Newaon Toolkit and evaluate it. Note that you cannot use DefGonst in the 
Inspector since it’s a compile-timc function. Just substitute the second argument 
in the DefConst function for kDefaultCharlDObj in the function to evaluate it. 
rhen you can try things like diis: 

X ;= :NewCharlD(nil); 
i440DD01 <CharID, length 4> 

ExtractChar(Xf 2); 

#6 $\00 

X ^ewCharIDY"ai>cd"); 

#4410FC9 <CharID, length 4> 

ExtractChar{x, 2); 

1636 ?c 

ExtractByte(x^ 2); 
il8C 99 


Q 

A 

Q 


IVhat is your favorite color? 
Llama fur beige. 


In my appikation / have a dPkmreView that can display a vmiahle number of pktitres. 
Right now I axate a htmch of picture slots in my appikation and then inake anothe?' slot 
at rtm time that k an array of those hmts. There must he an easier way. 


A 
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You’re right; there is an easier way You can use the GetPict^Bits hinction in 
your ProjectData file to read in the bitmaps. Note that you’ll first have to open 
the resource file that contains the pictures. 





// Open the resource file that contains the pictures. 

// Assumes the file “Pictures" exists in the project folder, 
r := OpenResFileX(“Pictures"); 

// Get an array of pictures, 
myPictures := [ 

GetPictAsBits{"TMDIS% nil), 

GetPictAsBits("Planet", nil) 

]; 


// Now close the resource file. 

CloseResFileX(r)j 

Once yon have the myPictures array, you can create a sJot of type Evaluate and 
just type **inyPictures” in the editor for the slot. Then you can use SetValue to 
set the icon slot of the clPicture view to one of the elements of the array. 


Q 

A 


Hmr do I put my &wn default pm'aw In the fax informamn slip? 

You can set up a default person in your SerupRoutingSlip method, which is 
called before the fax slip is shown. The argument to that method is used to set 
up the particular routing slip. In the case of a fax slip, there's a slot called 
“alternatives” which is an array of cardfile entries for the possible people to fax 
to. If there's just one entry, that's die person. The tax number will be set from 
die cardfile entry. So your SetupRoutingSlip method wotdd look like this: 


func(fields) 
begin 

// Check for a fax. 

if fields,category = 'faxSlip then 

fields.alternatives ;= SmartCFQuery("Llama"); 

//Do other stuff here, like put a title for the out box. 


Note that the fields.category is set to the same value you set in the routeSlip slot 
of a frame in your application's entry in the global routing frame. The 
SmartCFQuety function returns an array of cardfile entries that have strings 
starting with die string passed in. 


Q 

A 


I noticed that eve?y soup cntty has a _imiquelD slot. Just hou^ unique is it? 

The _uniqueID slot is only unique w'ithin that soup on that particular store. 
The ID will never be reused in that soup on that store. How^ever, it's not 
necessarily unique across stores (say, RAM and a PCMCIA card). 


Q 

A 


What is the ground velocity of an unladen llama clhubinga S% grade? 
Whai do you mean — Mexican or Venezuelan? 


Thanks to Glen Raphael and our PIE Partners Have more questions? Need mare answers? 

for the questions used in this column, ond to Take a look at PIE Developer Info on AppleLink.* 

jXopher, Todd Courtois, Bob Ebert, Mike Engber, 

Kent Sondvik, Mourice Sharp, ond Scott ("Zz'j 
Zimmermon for the answers.* 
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KON & BAL'S PUZZLE PAGE 


Monitor Madness 


See if you can solve this programming puzzle, presented in the fyrm of 
a dialog between Konstantin Othmer (KON) and Bruce Leak (BAL). 
The dialog gives clues to help ym. Keep guessing until you're done; your 
score is the number to the left of the clue that gave you the cmrect 
answer. Even if you never run into the particular problems being solved 
here, youHl learn some valuable debusing techniques that will help you 
solve your own programming conundrums. And you'll also learn 
interesting Macintosh trivia. 

KON Wth all the talk of PowerPC, I should give you one of the really nasty 
PowerPC bugs IVe been working on. But to be fair to those who aren’t 
np to speed yet, namely one Til give yon a bug that’s right up 
your alley. 

B.^VL You’re a saint. 

KON Have you heard of the Display Enabler software that w^ent out with the 
new 17'inch Multiple Scan display and is part of System 7,5? It lets 
you dynamically change your monitor configurations, such as your 
menu bar screen and resolution on Multiple Scan displays, 

BAL You mean I can Option-drag the menu bar across screens in the 

Monitors control panel and it changes dynamically? Totally cool! I 
hate that “takes effect on restart” stuff. This means that I can help out 
all those multimedia applications that don’t understand my second 
monitor is color, 

KON And if you get one of the Multiple Scan displays, you can double-cUck 
on a screen in Monitors and change its resoludoii on the fly. Last time 
I saw someone try that on a W^mdows machine, it crashed! 

B.AL Give ’em ten more years, I’m sure they’ll get it right, 

KON With Display Enahler, the system automatically keeps wdndows on the 
screen when you move the menu bar. It even moves your icons to 
reasonable positions. If you’re using the new scriptable Finder, the 
icon relocation is awesome. Sometimes I get the feeling it can read my 
mind. 



KONSTANTIN OTHMER 
AND BRUCE LEAK 


KONSTANTIN OTHMER AND BRUCE LEAK 

absconded to fhe ski slopes immediotoly alter 
writing this Puzzle Page^ leaving develop without 
a bio. Fortunately, they had AppleLink hooked up 
to their cellular phone-based Newtons, so they 


could pen their bro remotoly. Although develops 
editors repeatedly sent them mail requesting a 
bio, all they ever got back was a cryptic message 
□bout Crinoline Gopher and Brunch Creek. Go 
figure.* 
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BAL 

KON 

BAL 


KON 


BAL 


KON 

BAL 

KON 

BAL 

KON 


BAL 

KON 

B.4L 

KON 


B.\L 

KON 

BAL 

TOO KON 


BAL 


Wiiit. Are you running Macintosh or a Ne\vton? 

I la ha. 

OK, back to the puzzle. M'Tiat’s the bug? Was there troul>le with 
applications that hide windows by moving them off the screen? Those 
window^s wouldn’t l)e able to he located after being moved along with 
the menu bar. 

We handle diat case for the most part, although that^s a pretty cheesy 
w^ay of hiding windows* Apparently some developers have trouble 
figuring out what Show^Hide does. The bug 1 have for you is w ay 
l)etter than diat. 

Yeah, sure. It probably only happens on a particular machine, in one 
magic case that’s really hard to reproduce, and only w hen MacsBug 
isn’t loaded. 

No fair. \buVe played this game before. Actually, someone reported 
that w'hen you change the resolution of a monitor and then try^ to 
restart, the macliine hangs on boot. 

Wbll, it’s a goc:)d thing monitor reconfiguradons take effect without 
restarting, since restarting doesn’t w^ork an)Tnore! Does it happen if I 
don’t have Display Enabler installed? 

Without Display Enabler, you can’t change the resolution of the 
monitor. Solve the problem. 

Only under protest. How far does he get wTen he tries to reboot? 

Smiley Mac and that’s it. It dies right about where you would expect 
the death chimes. 

And it only happens on this one macliine? 

WTen we tried to reproduce it on an identical configuration we 
couldn’t. 

V\diat’s his configuration? 

Macintosh Quadra ^^00, on“bQard video connected to a 17-inch 
Multiple Scan display, mo hard drives, and System 7.1 with Display 
Enabler. 

How^ does he regain access to his machine? 

He resets parameter RAM (PRAiVl) by holding down Command- 
Opdon-P'R undl the machine chimes the second rime. Then 
everything boots fine. 

But it boots into the default video mode, not the one he specified in 
Monitors. 

Of course. Because die original Maemtosh was floppy-based, PRAM 
was added to hold a lot of system configiu-ation mformation, such as 
mouse speed, double-click time, and sound volume for each monitor. 
That way you could boot off of different floppies and still maintain all 
your system preferences. 

The iMacintosh II extended the use of PRAM to add support for 
multiple video cards and slot devices. Since PRAAI is in such short 
supply, there’s also a 'sem' resource that’s maintained by Monitors that 
contains the relative locations of the different monitors, as well as each 
monitor’s mode. The problem is that the 'sem' restiurce and your 
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PRAM are out of sync, so the system gets confused and bangs. Go fix 
your bug- Over, 

Nice theory but wrong. First of all, we restart right after closing 
Monitors. The last thing Monitors does is update the 'scrn' resoiUTe 
and tell the driver to update its PRAM settings. So there^s not much 
chance for them to get out of sync. Second, the 'scm' resource is read 
and acted upon at extension loading time, and weVe hanging way 
before that. 

BAL So something that's getting written to PRAJVl must be causing all the 
fuss. On his machine, use the DPRAM dcmd to check the PRAM 
locations related to video before and after changing the mode. To 
factor Alonitors out of the equation, boot and set the PRAM locations 
by hand and see if that's the only dependency, 

KON Slick sleuthing, BAL! It turns out diat PRAiM location that holds the 
new mode for the on-board video (in your case, $49) gets changed. If 
you change It using the SPR/\M dcmd rather than Monitors, the 
problem still occurs. 

BAL Drat. I was hoping that Monitors was somehow trashing the startup 
drive PRAM location. IVe always been looking for a good excuse to 
rewrite Monitors out of that Pascal morass. 'Phis certainly narrows it 
down. 

KON If you say so. But you can only get it to happen on this one machine, 
and how could video PRAM be related to Ixjoting, anyway? 

BAL It's going to he hard to get iMacsBug invxjlved since we're too early in 
the boot process. 

KON You could get MacsBug-like capabilities at boot time using BootBiig, 
but there’s no card around. 
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BAL So what’s special about this configuration? Is it a prototype 17-inch 
Multiple Scan display? 

KON Nope. He claims to he using a production unit. 

BAL What if you remove the extra hard drive? 

KON It boots fine. No problem. 

BAL You mean if I just turn off the external drive, the machine boots fine? 

KON Yep, 

Bj\L WTiat if I set the system to boot i)ft' of the external drive? 

KON There's no system on the external drive. But you can tell the system to 
set the startup disk there. It's not as if it checks for a valid boot vohime 
or anything. I've heard you can even set it to boot off of a Sega CD, 

B.AL So T put a system on there and set it as the boot drive. Wiat happens? 

KON It boots fine. 

B.AL But if 1 set the boot drive back to the internal drive, 1 crash? 

KON Nope. That seems to be working fine now^ too. 

BAL Altai ril remove the system from the external drive and try to reboot. 
Now I crash, right? 

KON Nope, The system seems to be booting fine now, Nice going, BMJ 
You fixed the only reproducible case! Cotiid you recap the symptom 
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and the fix so that I can just add them to the Read Me file and be done 
with it? 


BAL 

Yeah, yeah. Sc^mehow something must have changed on that external 
disk. Maybe the Finder wrote out some new boot blocks or removed 
some stale boot blocks when I trashed tlie System file. Can put the 

disk back to its original state? 

70 KON 

Well break into our hermetically sealed digital fiberoptic wireless 
remote personal information highway archive server and restore your 
disk image. The machine still boots fine. 

BAL 

If it^s not the disk, 1 must have changed something in PRAM. WTiat's 
the startup drive set to now and what was it when I dumped PRAM 
earlier? 

65 KON 

The long word that holds the boot drive (PRAM location $78-$7B) 
used to hold SO and now it holds SFFFFFFDF (a driver refNum), 
which indicates that youVe booting off the internal drive. 

BAL 

WTiat does $0 specify? 

KON 

That’s what PRAM gets set to when you don’t select a boot drive in 
the Startup Disk control panel. It tells the system to go look for a valid 
boot dri ve and boot off of the first one it finds. 

BAL 

Wien 1 set the boot drive to the internal drive using Startup Disk, the 

PR.AM location was set. UTat happens if I set it back to $0? 

60 KON 

You hang on lioot, same as before. 

BAI. 

Wiat if you put a System Pfolder on the external drive but leave the 

PRAM boot drive set to $0? 

SS KON 

You don’t hang anjunore, and the system boots off of the external 
drive. 

BAL 

^\nd if I drag that System Folder to the ti^ash? 

50 KON 

The system hangs on boot 

BAL 

Mdiat if I use a newly initialized external drive with the same SCSI ID? 

45 KON 

It boots fine. 

BAL 

Let’s recap for those just joining ns. The machine hangs on boot on a 
tw^o-drive system under these circumstances: the System Folder on the 
external drive has been deleted; there’s no default boot drive selected; 
and the video mode of the on-board driver is set to something other 
than the default. Did I forget anything? 

KON 

The solution. 

BAL 

So how does the system go searching for boot drives? 

40 KON 

If the device specified in PRAM doesn’t exist or isn’t bootable, the 
boot code starts with the device with the highest SCSI ID and looks 
for boot blocks. If they exist, it tries to boot off of that drive. If it 
works, great. If there’s no System Folder or Finder, it will start over 
with the next highest SCSI ID. 

BAL 

I bet if I put the same SCSI driver on both disks using Apple HD SC 

Setup, the problem goes away. 

KON 

You got a theory here, or w hat? 
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BAL 

Early in die boor process, the system heap is really small. When you 
pur the video driver into one of the new inodes tickled by Display 

Enabler^ it loads patches out of ROM into the system heap. Ihese 
patches fight with the SCSI driver for the limited system heap RAM. 

When no boot drive is selected, the boot code trolls the SCSI bus 
looking for a valid boot device. It loads the SCSI driver off the first 
candidate, starts booting, and finds there^s no valid System Folder 
present. So it goes to the next drive, sees that there's a different SCSI 
driver version on it, and tries to load that version. Because the video 
driver loaded its extended tables and forgot to grow the system heap, 
the load fails and the system hangs without a clue as to how to 
proceed. 

35 KON 

Wow! Fabulous theory, but wrong. If you get BootBug— a wonderful 
product for anyone wanting to debug system startup, by the way — 
and watch the SCSI Manager allocate space for the driver, it succeeds. 
Furthermore, when the system fails to boot from the first drive it 
finds, it throws eveiy'^thing away by calling InitZone on the system 
heap zone and starts over with the next drive. Your story about the 
video driver patches is accurate, but there's still enough room in the 
sy'^tem heap after they load. Your move. 

BAL 

OK, I need some tools. VVTiat have you got? Do you expect me to 
debug this with my bare hands? 

KON 

Well, we don’t have an emulator handy, but we could probably call in a 
few favors and get a BootBug NuBus card. 

BAL 

Now this should be easy! MTiere do I crash? 

30 KON 

You crash in code that’s monkeying around with the low-rnemory 
global at $DD8, UniversalInfoPtr. It’s the table that tells you 
everything you ever wanted to know abtiut this machine’s 
configuration: the clock speed, all kinds of I/O stuff, the kind of sound 
hardware, SCiSI hardware, on-board video, and luemoiT controller, the 
number of NuBus skjts . . . 

BAL 

OK, OK. What’s the problem? 

KON 

Well, it dereferences $DDS, makes some calculations with the offsets, 
and ends up with a bogus address and a bus error. 

BAL 

Where does $DD8 point? 

25 KON 

Into RAM. 

BAL 

That’s strange. All that configuration information should be in ROM. 

I’ll stop BootBug immediately and step spy on $DD8 to see who 
changes it. 

20 KON 

By the time BootBug comes in, the location is already changed. 

BAL 

Wait, BootBug loads first. It should come in before any other slots get 
called. 

15 KON 

It works that way on the Macintosh Quadra 610, 650, and 800 models 
and later (including the AV models). But you’re on a Quadra 900, and 
on-board \idea occupies the first NuBus slot. The video is already 
gray, so the primary^ INIT of the on-board video has already been 
called. 

BAL 

If I don’t set the new video mode, so that I boot successfully, where 
does $DD8 point? 
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KON Intfi ROiVl. 

BAL Alia! The video driver is doing something different because it sees it 
needs one of the extended inodes. It must patch SDD8 to change the 
configuration information for the video display* 

10 KON So? Wiat’s wrong with patching? Wiy does it w^ork when only one 
drive is involved? 


5 


BAL r got it! The video driver patches out $DD8 to replace the tables for 
the extended video modes. Then the hoot ccide starts kioldiig for a 
valid lioot drive. It finds the external drive, which has valid boot blocks 
since it once had a system on it, anfl tries to boot off of that. Wfiien it 
realizes there^s no valid System Folder on the disk, the machine 
performs a warm restart and tries the next drive. 

KON Nothing new here yet. 

BAL The problem is that wLen the system restarts, it reinitializes the 

system heap, throwing out the video patches, but doesn't reinitialize 
$DD8 since that's set very early by the boot code to describe die type 
of machine that was detected. Now SDD8 points to garbage. As soon 
as someone tries to reference $DD8 they get garbage, resulting in a 
bus error. The machine doesn't know^ what to do and locks up. 

KON Why don't you get a system error or at least the death chimes? 

BAL Since there's no w^ay to draw' to the screen imtil a video driver is 

successfully found and opened, the death ehimes were designed to 
audibly indicate where in the l)OQt process failure occurred. Once the 
video driver is successfully opened, the death chimes error handler is 
replaced w^ith the standard system error handler. Bur when the external 
drive failed to hoot, the video driver was thrown out and the error 
occurred before it was reopened, so no error message coulil he 
displayed. 

KON Precisely. Since all the problems happen in ROM long before we can 
get control, unless we want to do one of those nasty Darin-changed- 
the-boot-blocks patches, we can't write those extended modes to 
PKAM. So we w^ait until the Display Enabler INIT loads to 
synchronize the display with die 'sem' resource. Trying to debug 
things at boot time is hard enough, especially when they happen 
befi^re BootBug loads. 

BAL Nasty. 

KON Yeah. 


SCORINO 

75-100 If you're so smart, you write the next one. 

50-70 You're qualified to rewrite the boot code. Please use C this time. 

25-45 You're quolified to rewrite the boot code in Pascal. 

5-20 Study the pipeline instruction architecture used by the 68000 versus the emulator to get o 
head storf for next time.® 

Thcinks to Ion Hendry, Carl Hewitt, and Mike Puckett for reviewing this column,* 
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History of the 
Dogcow, Part 2 


In Issue 17, we told part 1 of the history of the dogcow. 
Well warn you again: If you don’t know what or who 
the dogcow is, or yon don’t care for Apple cultural 
minutiae, you should just flip past diis column. 

DISTRIBUTION OF TECH NOTE #ai 

We left off at the point where the former Macintosh 
Technical Note #31, “The Dogcow/^ had been created. 
The question then was how to distribute it. Mark 
Johnson and I both thought that since it was an April 
Fool’s joke anyway, the best daing would l)e to just 
include it in the April monthly mailing to Apple 
Partners and Associates; we’d drop it from die 
subsequent batches.^ with the direct intent of making it 
a curio. The idea w^as that the people wiio w^ere 
currently in the Macintosh conimnnity would get it and 
everyone else wouldn’t. We very intentionally were 
trying to build an aura around it. The April 1989 
mailing is the only time this Tech Note was ever in 
print under the official auspices of Apple. 

There was a bit of a lag time betw^een the writing of the 
Note and the actual release; by the time it went out, I 
actually had forgotten about it. The response was 
immediate and intense. Internally I received a couple of 
vaguely threatening calls from people claiming false 
ow nership, but the overwhelming majority of people 
thought it was great. One gcndeman in the developer 
ct>mniunity toc^k offense saying diat “dogcow” was too 
close to “Dachau” and showed how the note had 
underpinnings of and-Semidsm. (I showed this one to 



MARK ("THE RED") 
HARLAN 


my Jewish father-in-law, whc3 had to be resuscitated, he 
was laughing so hard.) 

Aside from diat, it really struck a chord with the 
developer community like nothing Fve seen before or 
since. I received about 40 pieces of fan mail that mondi. 
Developer Technical Support (DTS) must have gone 
for a year before there was a batch of e-mail that didn’t 
have a dogcow reference in it. In fact, to this day people 
say to me, “Mark Harlan? I know your name from Tech 
Notes” — but it’s die only one I ever wTote. 

Then came the concept of a Developer CD as a vehicle 
for distributing Tech Notes electronically {along with 
sample code and more). 1 was overseeing that project, 
and immediately we had an interesting conundrum: We 
w'anted all information in electronic format, yet W'hat 
were we going to do with Tech Note #3 1 ? Merely 
slipping it into the Tech Notes stack seemed like 
disaster, hut then it didn’t really feel right to omit it. 

Again, it was Mark Johnson w ho came to the rescue 
with the excellent idea of burying the Tech Note. So on 
the early CD, “Phil and Dave’s Excellent CD,” you 
have to go through a hixarre sequence of commands to 
bring it up. B7ven now, tradition requires that I not give 
die details, but it involves Shift-Option-cIicking and 
typing “grazing off a cliff,” and it emits “MoolF’ and 
“Foom!” sounds. (For the “Mooli” sound we look a 
real cow' and dien Zz said “ffp’ inuj a MacRecorder; the 
“Foom!” is just the same sound played backwards.) It 
took a W'hile for anyone to fintl the Note using any 
technique, and Fve never heard of anyone doing it 
except through ResEdit. 

The Note stayed on the first few Developer CDs. The 
access technique changed from disc to disc, and not 
even f knew how^ to do it after the original “Phil and 
Dave.” Somewdiere along the line the Note was 
dropped from the CD altogether. 

OTHER DOGCOW PARAPHERNALIA 

Btjodeg T-sliirts started appearing. There w as an 
apartment near Apple headquarters that started flying a 
dogcow flag. The stack version of the Ni)te had a 
watermarked background that someone removed pixel 


MARK ("THE RED") HARLAN went through extensfve 
deprogramming alter six years at Apple. Unfortunotely the therapy 
didn't hold and he has since joined yet another cult: General 
Magic. In a recent interview, Mark was asked if he had any words 
of wisdom on the dogcow. "Yeah. Warn everyone that both the 
dogcow logo and ^Moofr are trademarks of Apple Computer. You 
don't ever want to be in the position of having to answer 'WhoI 
are you in for?' with 'Bootleg T-shirts."'* 


Our friend in the LaserWriter Page Setup Options 
dialog/ normal and flipped vertically: 

-=r=K 
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hy pixel before posting it to the InterneL Several 
developers were nearly thrown out of a movie theater 
at MacHack for “Moofing” before a movie. 

O 

In addition to the Tech Note there are three pins: 
green background, the most common; red background 
with Kanji (die word on the pin actually is pronounced 
^Moo-aarm!” because Japanese dogs don’t woof, they 
say something like “aami-aaim”); and the super-rare red 
background with “Mootl^ which are misprints of the 
Kanji batch. Also, there’s a dogcow window^ sticker. x411 
of these were given away in DTS labs, and all but the 
window sticker have lieen collected up a long lime ago. 

If you think of the dogcow fathers as being Zz 
Zimmerman, Mark Johnson, and me, there’s only one 
dogcow' shirt that received our supervision and 
approval: the black DTS sweatshirt with the small 
dogcow on the chest (designed hy Toni Trujillo). I also 
designed the graphic for a DTS gift that was a shoulder 
hag with all incarnations of the dogcow on it (flipped, 
rotated, and inverted). Unfortunately the bag w'as 
incredibly cheap and most of them have self-destmcted. 

Chris Derossi and Mary Burke designed a dogeow' 
mousepad and even went so far as to call Pepsi-Cola to 


get the exact color of Mountain Dew green for the 
background. They made 500 of these and 1 wrote an 
insert that w^ent into the packaging. Aside from the 
original Tech Note, it’s the only thing I’ve ever written 
about dogcatde — until these dezychp columns. 

DOGCOW TRIVIA 

Somewhere along the Hue I baptized the dogcow^ 
“Clarus.” Of course she’s a female, as are ail cows; 
males would be referred to as dogbulls, but none exist 
because there are already bulldogs, and God doesn’t 
like to have naming problems. 

Now things are much bigger than they were then — 
both in number of developers and number of Apple 
employees. The dogcow regularly appears on 
documents that are no longer comiected to DTS, or in 
some cases (such as Scott Knaster’s books) not even 
from Apple. In a sense, the dogcow has become 
mainstream; people are copying it — and that’s exactly 
what I was fighting against in the first place (not to 
mention that she, and her “Mootl” cry, are bona fide 
trademarks of Apple Computer). To put a stop to all 
this, I’m threatening to kill her off, hut dnwlop^s editor 
has become such a fan that she’s not sure she’ll accept a 
“Dogcow is Dead” column. Stay tuned! 


How’re we doing? 

If you have questions, suggestions, or even gripes about develop, please don’t keep them to yourself. 
Drop us a line and let us know what you think. 


Send editorial suggestions or comments 
to AppleLink DEVELOP or to: 

Caroline Rose 
Apple Computer, Inc. 

20525 xMariani Avenue, xWS 303-4DP 
Cupertino, CA 95014 
AppleLink: CROSE 
Internet: crose@applelmk.apple,Gom 
Fax: (408)253-8521 


Send technical questions about develop 
to: 

Dave Johnson 
Apple Computer, Inc. 

20525 Mariani Avenue, M/S 303-4DP 
Cupertino, CA 95014 
AppleLink: JOFINSON.DK 
Internet: dkj@apple.com 
CompuServe: 753 00,715 
Fax: (408)253-8521 


Please direci: all subscription-related queries to develops P.O. Box 531, /Mount Alorris, IL 61054- 
7858 or AppleLink DEV SUBS (or, on the Internet, dev.subs@applelinLapplexom). Or call 
1-800-877-5548 in the U.S., (815)734-1116 outside the U.S., or (815)734-1127 for fax. 
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99 

kAEWantReceipt, Macintosh 
Q& A 99 

LAGCreator, Apple Guide and 1 1 
kAGDBTypcBiLAny bit^ Apple 
Guide and 10 

kAGDefault flag, Apple Guide and 
13 

kAGErrDatahaseNotAvaiiable, 
Apple Guide and 13 
kAGErrDatabaseOpen error, 

Apple Guide and 19 
kAGFileDBlypeHelp, Apple 
Guide and 13 

k.\GFileDBTypeOther files, Apple 
Guide and 11 

kAGFileMain, Apple Guide and 
11 

kAGFileMixin, Apple Guide and 

11 

kAGViewFullHowdy view, Apple 
Guide and 14-15 
kAGVi ew Si n gl eTo pi cs vi ew, App f e 
Guide and 15 

kDrawButtonFilled, hierarchical 
lists and 63 

kDrawIntermediate, hierarchical 
lists and 63 

kEraseButtonArea, hierarchical 
lists and 63, 69 

kHasTwastDown, hierarchical lists 
and 63 


'kind’ resources, preferences files 
and 82“83 

kOldShowSublist, hierarchical lists 
and 63 

“KON & BAEs Puzzle Page” 
(Othmer and Leak), Monitor 
Madness 108-113 
kOn lyRedrawButton, hierarchical 
lists and 63, 71, 72 
kOSADontUsePhac, OSA and 37 
kOSANullScript, OSA and 33 
kOSAUseStandardDispatch, OSA 
and 37 

kSelectedElement, hierarchical 
lists and 63 

kShowSublist, hierarchical lists 
and 63 

L 

Leak, Bruce 108 
linked lists, storing data in S9~62 
list cells, drawing 71-74 
List Manager 64 
List Manager lists 59 
LoadScriptFrom Fi I e (Si mpl iFace) 
32 

loops, expanding (PowerPC) 56 

M 

Macintosh Easy Open, preferences 
files and 86 

MadntoshQ&A 92-102 
MacsBug messages, QuickDraw 
GXand 42 

MakeDataExecutaljle, Power 
Macintosh anti 53 
M a keTw i stD o w n hd e m en t, 

hierarchical lists and 60, 61, 65 
mcActio n S e tKey s En a h 1 ed, 
QuickTime and 23 
mcActionShowBalloon, 
QuickTime and 24 
MCCIick, Quick'rime and 23 
MCEnableEditing, QuickTime 
and 25 

MCGetControllerlnfo, 

QuickTime and 25 
MCGetiMenuString, QuickTime 
and 25 

xMCIdle, QuickTime and 24 
MCIsPiayerEvent, Qui ckTime 
and 23, 24 

MCSetUpEditMenu, QuickTime 
and 25 

MegaMovies application 24 
memor}^ dereferencing 57 


Microseconds, Power Macintosh 
and 54 

iMinow, Martin 58 
mix-in guide database files, x\pple 
Guide and 19 

MoGuide sample application, for 
Apple Guide 7, 9 
Monitors control panel, KON & 
BAL puzzle 108-110 
mouse events, hierarchical lists 
and 67-71 

movie controller editing, 
QuickTime and 25 
Multiple Scan displays, KON & 
BAL puzzle 108-113 
MyBuildFIierarchy, hierarchical 
lists and 65, 76 
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65 
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and 65 

N 

NewMovieController, QuickTime 
and 22-23 

NewMovieFrom Fi le, QuickTime 
and 22 

NewPreferencesFile 89 
Newton Q & A: Ask die Llama 
103-107 

NewTwistDownList, hierarchical 
lists and 64 
nonrectangular movies, 
QuickTime and 23 
notices, QuickDraw CiX and 
41-42 

NuBus frame buffers, QuickDraw 
13 J and 49 

o 

objects, attaching scripts to 33-35 
Object Support Library (OSL), 
Apple Guide and 16 

ObjiModelEvents-cp file, OSA and 
29, 30 

ObjModelTokensE file, OSA and 
29 

“OCE Mai! Enclosures” volume, 
Macintosh Q & A 93^94 
“On Panel Hide” action, attaching 
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Apple events to 17-18 
Open Application Apple event, 
OSA and 38 
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OpenDefiaultC^omporient 
OSA and 33 
QuickTime and 22 
Open Documents Apple event, 
preferences files and 85 
OpenMovieFite, QuickTime and 
22 

OpenNewEdition, Macintosh 
Q&A 101 

Open Preferences File 89 
'open' resources, preferences files 
and 86“88 

Open Scripting ^Architecture 
(OSA) 26^0 
OSA (Open Scripting 
Architecture) 26-40 
OSACompileExecute 35 
OSACompile 35 
OSADoEvent 37, 38 
OSAExeciiteEvent 37 
OSAExecute 33 
OSAGetSource 36 
OSMDs 32, 33 
OSALoad 32 

OSASetResuineDispatchProc 37 
OS AS tore 32, 36 
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movie 23 

Othmer, Konstantin 43, lOB 
owner Name, preferences files and 
89 
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95 
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& B.AL puzzle 109-113 
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47 

'pdoc' event, iVlacintosh Q & A 
100 
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and 8B 
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QuickTime and 24 
Power Macintosh 

compared with a xMacintosh 
Quadra 45-46 
converting code for 77 
graphics speed and 43-54 
PowerPC 
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55-57 

graphics speed and 43-54 
Powers, John 6 


preferences files 

contents of 88-89 
icons 83 

implementing 81-91 
opening 84=88 
standard preferences library 
89-91 

Preferences File Exists 90 
■pref file type, preferences files 
and 82 

presentation window (Apple 
Guide) 7 

“Programming for Flexibility: The 
Open Scripting Architecture” 
26-40 
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104-105 

protoGlance, Newton Q & A 104 
p ro to Pi ctRad io Bu tto n, Newton 
Q&A 105 

protoTable, Ne\\ton Q & A 104 

Q 

QDError, QuickDraw 1.3.5 and 
46 

'QLfy' Gestalt selector, Apple 
Guide and 19 
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QuickDraw 1.3.5 

compared with QuickDraw^ 
1.3.0 45 

and Power Macintosh 
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reducing overhead 49-50 
tim ing roiiti nes 51 -54 
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QuickDraw GX 
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support 22-25 

R 

RcadPreference, preferences files 
and 90 

recursion, hierarchical lists and 62 
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13.5 and 47 

“Right Way to Implement 
Preferences Files, The” 
(Woodcock) 81-91 

s 

ScaleMatrix, Alacintosh Q & A 93 


scope of variables (PowerPC) 56 
scpF (typeOSAGenericStorage), 
OSA and 32,34 

ScripiableObjects.cp file, OSA and 
30 

ScriptableObjects.h file, OSA and 
29 

Script Editor (AppleScript), OSA 
and 26, 31-32 
scripts 

attachjng/embedding with 
OSA 26-40 

importing from the Script 
Editor 31-32 

selector-based traps, Macintosh 
Q & A 92 

SellText, xMacintosh Q & xA 95 
Set Data Apple event, OSA and 
36, 38 

SetlText, Macintosh Q & A 95 
S e tP r e fere ncesFi 1 e Ve rs i o n, 
preferences files and 90 
SetPropert)'^, OSA and 34, 35 
SetlrackDiniensions, Macintosh 
Q& A 93 

SetTrackMatrix, Macintosh Q & A 
93 

Set Value, Newton Q & A 
104-105 

ShieldCursor, QuickDraw 1,3.5 
and 47 

SimpliFace.cp file (SimpliFace) 
30,38 

ShnpiiFace sample program 27, 
28-40 

debugging 31 

SimpliFace Startup script 31 
skank device, QuickDraw' 13.5 
and 46-47 
Smith, Paul G. 26 
“SomewEere in QuickTime” 
(Hoddie), basic movie playback 
support 22-25 
Speech Manager, Macintosh 
Q&A 100-101 
srcBic pen mode, Macintosh 
Q & A 95 

standard preferences library, 
preferences files and 89-91 
SrdMutPreHandler, OSxA and 39 
'STR ' resources, preferences files 
and 85-86 

suiTogate device, QuickDraw^ 1.3,5 
and 46-47 

SysError, QuickDraw 1.3.5 and 
46 
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system routine usage (graph) 44 
systemwide help, Apple Guide and 
' 8 

T 

TContext::ReplyToContexr, 
AppleGuide and 18 
TestSimpleWindow sample script, 
OSAand 30 

'TEXT' file type, preferences files 
and 88 

Text to Speech, Macintosh Q & A 
100-101 

TimeBlitProc, QuickDraw 1.3.5 
and 51-54 

timing routines, QuickDraw 1.3.5 
and 51-54 

’TMPL' resources, preferences 
files and 88 

TObjModelToken class, OSA and 

29 

topic ID numbers (Apple Guide) 
15 

transfer modes, QuickDraw 1J.5 
and 47 

Translation Manager, preferences 
files and 86-88 

Trays dialog, Macintosh Q & A 
93 

triangular burtons 59, 62, 64-65, 
66, 69, 72, 74 

'FScriptableObject class, OSA and 
29, 34 
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(SimpliFace) 36 
" 1 S cri p ra bl e Ob j ect:: Set Prop er ty 
(SimpliFace) 34, 35 
TScri ptAdministrator: :DoScri pt 
(SimpliFace) 35 
d ScriptAdrninistrator, OSA and 

30 

TSirnpliFacecHandleEvent 
(SimpliFace) 38 
tuist-down LDEF, hierarchical 
lists and 64, 69 

drawing code 71-74 
TwistDown library, hierarchical 
lists and 59, 63^ 78 
twist-down lists 

building 66-67 
data specifications for 76-78 
TwistDow^n Pri vateRecord, 
hierarchical lists and 65 
TwistDownRecord, hierarchical 
lists and 60 

t>^e Wildcard, OSA and 36 
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_uniqiieID slot, Newton Q & A 
107 

Unsigned Wide, Power Macintosh 
and 54 

update events, QuickTime and 23 

V 

variables, scoping (PowerPC) 56 
vdigs, Macintosh Q & A 101-102 
VersRec, preferences files and 90 
Vers' resources, preferences files 
and 83-84, 90 

‘Mew From the Ledge” (Jones) 
79-80 

viewTdleFrequencv, Newton 
Q&A 104 

viewIdleScript, Newton Q 8c A 
104 

w 

WaitNextEvent, Macintosh 
Q & x\ 98-99 

warnings, QuickDraw' GX and 
41-42 

WideSuhtract, Pow er Macintosh 
and 54 

window alignment, QuickTime 
and 24-25 
Woodcock, Gary' 81 
WricePreference, preferences files 
and 91 

write-through memory' 53 
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RESOURCES 


Apple provides a wealth of information, 
produOs, mid services to assist 
developers, A PDA, Apple} source for 
developei' tools, and Apple Developer 
University are open to anyone who 
wants access to development tools and 
instrumm. Developers may access 
additional infof'mation and services 
through Apple} Developer Programs. 


APDA To order products or receive a 
CO m pi i m enta ry co to log ^ call 1 -800-2 82- 
2732 in rhe U.5., 1-800^37^3029 m 
Canada, [716)871-6555 interrtotfonally, or 
1716)871'6511 for fax. You can also order 
electronically (AppleLink APDA; Internet 
opdo@applelink.opple.eoin; America Online 
APDAorder; or CompuServe 76666,2405) 
or write APDA, Apple Computer, Inc., P.O. 
Box 3 19, Buffalo, NY 14207-0319. 


APDA offers convenient worldwide 
access to development tools, 
resources, training products, and 
information for anyone interested in 
developing applications on Apple 
platforms. Customers receive the 
quarterly APDA Tools Catalog 
featuring over 200 Apple and third- 
party development products. There 
are no membership fees. APDA 
offers convenient payment and 
shipping options, including site 
licensing. 

Apple Developer University 

(DU) provides training designed to 
increase your software development 
productivity. The curriculum 
includes courses to get you started 
programming on Apple platforms, 
as well as advanced, in-depth 
training on the newest Apple 
technologies, such as Pow^erPC, 
OpenDoc, QuickDraw^ GX, and 
Newton. DU offers courses in 
Cupertino CA and at selected 
training locations. The DU 
Extension partner located in 
Portsmouth NH also schedules 
selected courses in its facilities* 

In addition to classroom training, 
DU offers multimedia self-paced 
courses and low^-cost mini-course 
tutorials. 

The Associofes Program is Apple’s 
primary program for developers 
across all Apple technologies, 
including Macintosh, Personal 
Interactive Electronics (such as 
Newton), and multimedia. Ids a 


Apple Developer University The 

registrar at (408)974-4897 can reserve 
your place or send o current Curriculum 
Guide and Course Schedule. You can also 
send an AppleLink to DEVUNIV or write 
Developer University Apple Computer, Inc., 
20525 Marioni Avenue, M/S 305-1TU, 
Cupertino, CA 95014. Self-paced products 
should be ordered directly through APDA. 


low-cost, self-support program that 
also provides a connection with 
Apple and fellow developers, 
information on new technologies, 
and discounts on equipment. 

The Apple Multimedia Program 

is designed for developers interested 
in the emerging multimedia market. 
Program features include a quarterly 
mailing and discounts on third-party 
products, training, and events. 

The Macintosh Technology 
Partners Program is open to 
xA.pple-selected strategic developers 
focused on Macintosh technology, 
including PowerPC, QuickTime, 
(JuickDraw^ GX, and PowerTalk. In 
addition to receiving the same 
development information and tools 
as members of the Associates 
Program, Macintosh Technology 
Partners receive programming-level 
development support via electronic 
mail. Membership in this program is 
limited to strategic developers w'ho 
direedy contribute to Apple’s long¬ 
term product plans and business 
objectives. 

The PIE Partners Program is 

open to Apple-selected strategic 
developers focused on Personal 
Interactive Electronics. It offers the 
same core features as the Associates 
Program, but also includes 
progra m m i ng-1 eve 1 deve lo pm e nt 
support via electronic mail, 
additional hardware purchasing 
privileges, marketing programs, and 
media production assistance. 


Apple Developer Progroms Call the 
Developer Support Center at (408)974- 
4897, AppleLink DEVSU PRO RT, or write 
20525 Marioni Avenue,^ M/S 303-21^ 
Cupertino, CA 95014, br Information or an 
application brm. Developers outside the U.S. 
□nd Canada should insfeod contact the 
Apple office In their country for Inbrmotion 
□bout developer programs. 








Apple Computer, Inc, 
20525 Mariani Avenue 
Cupertino, CA 95014 
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